docs: say to stop an extension before updating it

`update` deletes the old folder, so a running container would read
deleted files and lose what it writes. The admin guide now says to run
`stack down <id>` first and `stack up <id>` after, shows the sample
output in its real order without a commit subject, and says that a
shipped `.env` is not copied. ADR-022, the stack reference and the
operator command map say the same, and describe the held Ctrl-C and
the replaced `.source.toml`.

Author: arthware-dev

docs/admin-guide.md

@@ -756,6 +756,14 @@ If you do not give an id, `add` asks which extension to install. `add` never ins
 
 > ⚠️ **Do not change the files that `add` installed.** If you change one of them, `update` stops for this extension. Files that you add to the folder are kept. To change the code of an extension, see [Extensions that you develop](#extensions-that-you-develop).
 
+> ⚠️ **Stop a running extension before you update it.** `update` deletes the old folder. A running container then reads deleted files, and the files that it writes during the update are lost.
+
+To stop the extension, run:
+
+```bash
+./stack down hue
+```
+
 To update all extensions that you installed with `add`, run:
 
 ```bash
@@ -771,27 +779,27 @@ To update one extension, give its id:
 `update` gets the newest version of each extension from the default branch of its repository. This is the version that `./stack extensions list` compares with. Extensions from the same repository share one download. Each extension then gets one line:
 
 ```
-  Fetching https://github.com/famstack-dev/famstack-extensions...
      toaster      installed by hand, not updated
-  ✓  hue          updated to 3c9d2f1  "feat(hue): switch scenes"
+  Fetching https://github.com/famstack-dev/famstack-extensions...
+  ✓  hue          updated to 3c9d2f1
      Apply the new code with: stack up hue
      web          up to date
 ```
 
+`updated to` shows the newest commit of the repository. This commit can be a change to a different extension.
+
 **What `update` does:**
 
 1. It compares the installed version with the newest version in the repository. If they are the same, the extension is **up to date**. A change to a different extension of the same repository is not an update.
 2. It checks the files that `add` or the last `update` wrote. `.source.toml` records each of these files. If one of them is changed or missing, `update` stops for this extension.
-3. It writes the new version into `~/famstack-extensions/.incoming/`.
+3. It writes the new version into `~/famstack-extensions/.incoming/`. It does not copy a `.env` file that the repository contains, because `./stack up` writes this file.
 4. It checks the files again, in case they changed while `update` asked a question.
 5. It moves all other files of the old folder into the new version. For example, it keeps the `.env` file that `./stack up` writes. It also keeps a configuration file that the README asks for. If the new version has a folder with the same name as your folder, `update` moves your files into it.
 6. It puts the new folder in the place of the old folder. Then it deletes the old folder.
 
-If a step fails, `update` puts the old folder and your files back. If it cannot put a file back, the message shows where the file is.
-
-> ⚠️ **Run `./stack up <id>` immediately after an update.** A running extension continues to use the old files until you start it again.
+If a step fails, `update` puts the old folder and your files back. If it cannot put a file back, the message shows where the file is. If you press Ctrl-C while `update` moves files, it completes the move first and then stops.
 
-To start the extension with the new code, run:
+`update` does not start the extension. To start it with the new code, run:
 
 ```bash
 ./stack up hue

docs/adr/adr-022-extensions-are-copied-from-a-repo.md

@@ -107,7 +107,13 @@ admin.
 The strings in `.source.toml` are TOML basic strings. A file name outside ASCII
 is written as it is, and control characters are escaped. When the source is a
 local directory, `add` records its absolute path. Because of this, `update`
-finds it from each working directory.
+finds it from each working directory. `add` does not resolve symlinks in the
+path, because a catalog configured through a symlink must still match.
+
+The copy leaves out a `.env` at the root of the extension and does not record
+it, because `stack up` writes this file on each start. The copy also removes a
+`.source.toml` that the repository ships, before it writes its own. A shipped
+symlink would otherwise send the record to a file outside the folder.
 
 ### 4. The catalog is a configuration key
 
@@ -199,9 +205,17 @@ does not change it. The invariant: `update` deletes only files that `add` or
   includes Ctrl-C. When that fails too, the message names the path in
   `.incoming/`. `update` never deletes a staging folder that holds a kept
   file.
-- `update` starts nothing. For an extension that is set up, it shows
-  `stack up <id>`. `stack up` recreates the containers and the bot runner.
-  `stack restart` does not reload the bot runner.
+- `add` and `update` hold back Ctrl-C while files move and folders swap.
+  They raise it after the swap is complete. A hard stop, such as a power
+  cut, is not covered.
+- `update` starts nothing and stops nothing. For an extension that is set
+  up, it shows `stack up <id>`. `stack up` recreates the containers and the
+  bot runner. `stack restart` does not reload the bot runner.
+- The admin stops a running extension before the update. A running
+  container reads the deleted old folder, and loses what it writes there.
+- The line for an updated extension names the newest commit of the
+  repository only, because the clone is shallow. It does not know the last
+  commit that changed the extension.
 - A refusal of one extension does not stop the others. The exit code is 1
   when `update` refused one.
 

docs/agent/ops.md

@@ -38,7 +38,7 @@ If a precondition is missing, `./stack` prints exactly what to do. Don't improvi
 | `./stack update [<tag>]` | yes | no | moves the checkout to a release; restarts nothing, prints what to restart |
 | `./stack extensions list` | yes | no | the catalog's extensions and what is installed; creates no extension dir |
 | `./stack extensions add <id\|git-url> [<id>]` | refuses a second time | no | copies one extension into the first extension dir and starts nothing; warns first for any repo but the catalog (`--yes` skips only the question) |
-| `./stack extensions update [<id>...]` | yes | no | replaces installed extensions with the newest version on their repo's default branch; keeps every file it did not write (`.env`, local config), refuses when a file it wrote was changed, starts nothing (`stack up <id>` applies it); warns first for any repo but the catalog (`--yes` skips only the question) |
+| `./stack extensions update [<id>...]` | yes | no | replaces installed extensions with the newest version on their repo's default branch; keeps every file it did not write (`.env`, local config), refuses when a file it wrote was changed, stops and starts nothing (`stack down <id>` first, `stack up <id>` after); warns first for any repo but the catalog (`--yes` skips only the question) |
 | `./stack list` | yes | no | reports state |
 | `./stack status` | yes | no | runs health checks |
 | `./stack logs <id>` | yes | no | tail container logs |

docs/stack-reference.md

@@ -63,9 +63,13 @@ first extension dir, when it installs an extension there.
   the newest version of its path, on the default branch of the repository.
   It refuses when a file in `[files]` is changed or missing.
 - `update` moves each file that is not in `[files]` into the new version,
-  for example `.env`. It never deletes such a file, also when a step fails. It writes the new version into `.incoming/` of the
-  same extension dir and swaps the folders with two renames. It starts
-  nothing: `stack up <id>` applies the new code.
+  for example `.env`. It never deletes such a file, also when a step fails.
+  It writes the new version into `.incoming/` of the same extension dir and
+  swaps the folders with two renames, with Ctrl-C held back. It starts
+  nothing: `stack up <id>` applies the new code. Stop a running extension
+  first, because the old folder is deleted.
+- The copy leaves out a `.env` at the root of the extension and replaces a
+  shipped `.source.toml`.
 - Discovery reads the folder like any other stacklet folder.
 - `stack extensions` never changes a folder without `.source.toml`. Such a
   folder was put there by hand. `update` refuses a `.source.toml` without