family.py and bump-leg.py: every remedy that names family.py bump names --family-root, so each runs as printed (#927)

README.md

@@ -158,8 +158,8 @@ Git Bash runs step 3's bash command and its one line, tested in CI but for a
 typed `yes`, which its preflight cannot take there. Printed commands are quoted
 for a POSIX shell, so paste them into Git Bash. Only `shape-doctor.py`'s lines,
 `setup-project.py`'s family lines and `family.py`'s `NEXT`, `switch -c`, `add`,
-`cd` and `git rm -r --cached` lines are quoted for the shell they are printed
-in, PowerShell or Git Bash, on Windows.
+`cd`, `git rm -r --cached` and `bump` lines are quoted for the shell they are
+printed in, PowerShell or Git Bash, on Windows.
 Off Windows and in Git Bash, a path `shape-doctor.py` cannot print as itself is
 written `$'…'`: bash, zsh and ksh read that; dash (`/bin/sh` on Debian and
 Ubuntu) does not.

docs/handbook.html

@@ -472,7 +472,7 @@
 
       <!-- reads README.md § preamble: blob ddadd23a162129f7e64fefce899105661440c05c -->
 
-      <!-- reads README.md § Starting a project in a new organisation: blob e0d2b672082068b2df39ebf54801e068343a14c6 -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3f299067a481b09c78c5b159decc27db02f4d7cb -->
 
       <!-- reads README.md § The three legs: blob 4ec313e8424665e41fc92a4147808e0bd4901d78 -->
 
@@ -612,7 +612,7 @@ <h4>The one thing to read before electing it</h4>
 
     <section id="start">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob e0d2b672082068b2df39ebf54801e068343a14c6 -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3f299067a481b09c78c5b159decc27db02f4d7cb -->
 
       <p class="eyebrow">Setup</p>
       <h2>Start here</h2>
@@ -737,11 +737,11 @@ <h4>The tool offers the rest</h4>
           Printed commands are quoted for a POSIX shell, so paste them into Git Bash. Only
           <code>shape-doctor.py</code>&rsquo;s lines, <code>setup-project.py</code>&rsquo;s family
           lines and <code>family.py</code>&rsquo;s <code>NEXT</code>, <code>switch -c</code>,
-          <code>add</code>, <code>cd</code> and <code>git rm -r --cached</code> lines are quoted for
-          the shell they are printed in, PowerShell or Git Bash, on Windows. A shell started from
-          inside Git Bash inherits its <code>MSYSTEM</code>, which is how a tool tells Git Bash
-          apart, so a PowerShell started there is handed Git Bash&rsquo;s quoting, and a cmd.exe
-          started anywhere else is handed PowerShell&rsquo;s. Off Windows and in Git Bash, a path
+          <code>add</code>, <code>cd</code>, <code>git rm -r --cached</code> and <code>bump</code>
+          lines are quoted for the shell they are printed in, PowerShell or Git Bash, on Windows.
+          A shell started from inside Git Bash inherits its <code>MSYSTEM</code>, which is how a tool
+          tells Git Bash apart, so a PowerShell started there is handed Git Bash&rsquo;s quoting, and a
+          cmd.exe started anywhere else is handed PowerShell&rsquo;s. Off Windows and in Git Bash, a path
           <code>shape-doctor.py</code> cannot print as itself is written <code>$'&hellip;'</code>:
           bash, zsh and ksh read that; dash (<code>/bin/sh</code> on Debian and Ubuntu) does not.</p>
         </div>
@@ -1092,7 +1092,7 @@ <h4>What you have afterwards &mdash; the same on every platform</h4>
 
     <section id="partway">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob e0d2b672082068b2df39ebf54801e068343a14c6 -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3f299067a481b09c78c5b159decc27db02f4d7cb -->
 
       <p class="eyebrow">Setup</p>
       <h2>If it fails part-way</h2>
@@ -1129,7 +1129,7 @@ <h2>If it fails part-way</h2>
 
     <section id="ci">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob e0d2b672082068b2df39ebf54801e068343a14c6 -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3f299067a481b09c78c5b159decc27db02f4d7cb -->
 
       <!-- reads README.md § The three legs: blob 4ec313e8424665e41fc92a4147808e0bd4901d78 -->
 
@@ -1192,7 +1192,7 @@ <h2>Reading private legs in CI</h2>
 
     <section id="legs">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob e0d2b672082068b2df39ebf54801e068343a14c6 -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3f299067a481b09c78c5b159decc27db02f4d7cb -->
 
       <!-- reads README.md § The three legs: blob 4ec313e8424665e41fc92a4147808e0bd4901d78 -->
 
@@ -1448,7 +1448,7 @@ <h3>The InkRouter example</h3>
 
     <section id="doublepin">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob e0d2b672082068b2df39ebf54801e068343a14c6 -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3f299067a481b09c78c5b159decc27db02f4d7cb -->
 
       <!-- reads README.md § The double pin, and the lockstep invariant: blob 57fffa08ffad5476f8eae73dd3e8494a02e050c9 -->
 
@@ -1747,7 +1747,7 @@ <h2>Is this repository compliant? <code>openRepoShape --doctor</code></h2>
 
     <section id="park">
 
-      <!-- reads README.md § Starting a project in a new organisation: blob e0d2b672082068b2df39ebf54801e068343a14c6 -->
+      <!-- reads README.md § Starting a project in a new organisation: blob 3f299067a481b09c78c5b159decc27db02f4d7cb -->
 
       <!-- reads README.md § Carrying in-flight work to another workstation: blob b84512ad39c09085dfe6bf7ea694017f5e28c1dd -->
 

scripts/bump-leg.py

@@ -219,7 +219,8 @@ def open(cls, root_spec) -> "Project":
                 "Remediation: --root takes the ASSEMBLY ROOT — the repository "
                 "an engineer clones — not a leg and not a family holder. A "
                 "family's member pins are moved with `scripts/family.py "
-                "bump`; a leg has no legs of its own to move.")
+                "bump --family-root <holder> --member <Project> --to "
+                "<sha>`; a leg has no legs of its own to move.")
         data = load_yaml(path)
         if not isinstance(data, dict):
             raise Refusal("bump-leg-manifest-unreadable",
@@ -231,7 +232,8 @@ def open(cls, root_spec) -> "Project":
                 "'project-manifest'",
                 "Remediation: a family holder declares `kind: "
                 "family-manifest` and its members move with `scripts/"
-                "family.py bump`.")
+                "family.py bump --family-root <holder> --member <Project> "
+                "--to <sha>`.")
         return cls(root, data)
 
     @property
@@ -276,14 +278,18 @@ def leg(self, role: str) -> dict:
         # branch would never be reached, and the root is not a submodule of
         # itself to advance.
         if role == "assembly":
+            # `<holder>` IS A PLACEHOLDER (#927): `family.py bump` requires
+            # `--family-root`, and this tool is pointed at a root, which
+            # knows no holder, so it is said as `<Project>` and `<sha>` are.
             raise Refusal(
                 "bump-leg-assembly-is-not-a-leg",
                 "the assembly root is THIS repository, mounted at `.`, and it "
                 "is not a submodule of itself",
                 "Remediation: --leg takes `spec` or `code`. The assembly "
                 "root advances by its own commits; if you meant to move the "
                 "project's pin inside a FAMILY, that is `scripts/family.py "
-                "bump --member <Project> --to <sha>`.")
+                "bump --family-root <holder> --member <Project> --to "
+                "<sha>`.")
         for row in self.legs:
             if str(row.get("role")) == role:
                 return row

scripts/family.py

@@ -6610,13 +6610,17 @@ def _checked_add_target(family: Family, repository: str, project: str,
     """
     held = family.holding(repository, project)
     if held is not None:
+        # THE `bump` IT NAMES RUNS AS PRINTED (#927): `bump` requires
+        # `--family-root`, so the line names this holder, spelled by
+        # `shell_quoted` as `_add_command`'s is.
         raise Refusal(
             "member-already-present",
             f"{project} is already a member of {family.data.get('name')}: "
             f"the row {held.get('project')} pins {held.get('repository')}",
-            "Remediation: `family.py bump --member "
-            f"{held.get('project')} --to <commit>` moves an existing member; "
-            "`remove` takes it out. Adding it twice is not a way to move it.")
+            "Remediation: `family.py bump --family-root "
+            f"{shell_quoted(family.root)} --member {held.get('project')} "
+            "--to <commit>` moves an existing member; `remove` takes it "
+            "out. Adding it twice is not a way to move it.")
     # Everything the mount's `--force` would otherwise let past git, but the
     # cached store, which is asked below (#242).
     _checked_mount_path(family.root, project, path,
@@ -6733,6 +6737,8 @@ def _checked_member_id(family: Family, repository: str, project: str,
     row = _row_recording(family, project_id)
     if row is not None:
         name = row["project"]
+        # THE `bump` IT NAMES RUNS AS PRINTED (#927), with this holder's
+        # `--family-root`, as `member-already-present`'s does.
         raise Refusal(
             "member-duplicate-id",
             f"{project} is already a member of {family.data.get('name')} "
@@ -6744,9 +6750,10 @@ def _checked_member_id(family: Family, repository: str, project: str,
             f"{repository} is {row.get('repository')} renamed at the forge, "
             f"`family.py remove --member {name}` takes the old row out and "
             "this `add` then pins it under the new name; `family.py bump "
-            f"--member {name} --to <commit>` moves the row that is there "
-            "instead. Two projects that record one id are a fault in one of "
-            "their `project.yaml` files, mended in that project, not in the "
+            f"--family-root {shell_quoted(family.root)} --member {name} "
+            "--to <commit>` moves the row that is there instead. Two "
+            "projects that record one id are a fault in one of their "
+            "`project.yaml` files, mended in that project, not in the "
             "family.")