Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package bashupgrade
package main

import (
"os"
Expand All @@ -11,10 +11,10 @@ import (
)

// The alias is only useful if the binary behaves the same whatever name it was
// invoked by. This uses the real built binary (shared with the upgrade tests via
// buildDocket's sync.Once, so it costs no extra build) behind a dckt symlink.
// invoked by. This puts the binary TestMain builds once (binPath) behind a dckt
// symlink, so it costs no extra build.
func TestAliasInvocationMatchesDocket(t *testing.T) {
bin := buildDocket(t)
bin := binPath
dir := testsupport.TempDir(t)
alias := filepath.Join(dir, install.AliasName)
if err := os.Symlink(bin, alias); err != nil {
Expand Down
41 changes: 6 additions & 35 deletions docs/release/upgrading-from-bash.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,6 @@

This guide moves a Bash docket install, and the repositories it manages, to the docket binary.

An automated test runs every marked step below against saved copies of real `v0.9.2` and `v0.9.3`
installs. The exception is the download and checksum lines in section 3, which need the published
release. When something is outside that test, the guide says so.

## 1. Who this is for

Use this guide if all of these are true:
Expand All @@ -20,7 +16,7 @@ not supported.

## 2. Before you start

- In each repository, finish or kill every change that is in progress. The test covers
- In each repository, finish or kill every change that is in progress. The guide covers
repositories with no change in progress.
- In each repository, check out the default branch and make sure `git status` shows no changes.
The steps below commit and push to the default branch.
Expand All @@ -31,7 +27,6 @@ Run these commands outside any repository. They download the installer and the c
a new folder, check the installer against the checksum, then run it for Claude Code and Cursor. If
you use only one of them, drop the other one's `--harness` flag, here and in section 4.

<!-- upgrade-step: install-binary -->
```sh
mkdir -p ~/docket-download && cd ~/docket-download
curl -fsSLO "https://github.com/danielhanold/docket/releases/latest/download/install.sh"
Expand All @@ -41,8 +36,7 @@ sh install.sh --harness claude --harness cursor
```

The `shasum` line must print `install.sh: OK`. If it prints anything else, stop and do not run
`install.sh`. The download and checksum lines are checked by the release's own verification, not by
this guide's test.
`install.sh`.

The installer puts `docket` in `~/.local/bin`. Make sure that folder is on your `PATH`.

Expand Down Expand Up @@ -75,7 +69,6 @@ same way. It reports these Cursor paths as conflicts:

Delete the Cursor paths first. If you don't use Cursor, skip this block.

<!-- upgrade-step: cursor-takeover-remedy -->
```sh
rm ~/.cursor/skills/docket-*
rm -f ~/.cursor/agents/docket-plan-writer.md ~/.cursor/rules/docket-dispatch.mdc
Expand All @@ -85,7 +78,6 @@ Then delete the Claude Code paths and run the installer again from the same fold
`--harness` flags as in section 3. If you don't use Claude Code, leave out the two `rm` lines. The
failed run left no `docket` command, so run `sh install.sh` again, not `docket install`.

<!-- upgrade-step: takeover-remedy -->
```sh
rm ~/.claude/skills/docket-*
rm -f ~/.claude/agents/docket-plan-writer.md
Expand All @@ -98,7 +90,6 @@ Bash docket also left a `runtime.bash` setting in your global config,
`~/.config/docket/config.yml`. docket warns about it and ignores it. Delete these lines from that
file. The path on the `bash:` line is whatever your Bash install recorded.

<!-- upgrade-step: global-config-cleanup -->
```yaml
# >>> docket (runtime.bash) >>>
runtime:
Expand All @@ -108,7 +99,6 @@ runtime:

Then confirm the install. Both commands succeed, and `docket install check` prints no warning.

<!-- upgrade-step: confirm-install -->
```sh
docket version
docket install check
Expand All @@ -119,7 +109,6 @@ docket install check
Do this in every repository that has a `docket` branch. Replace `<repo>` with the repository's
folder.

<!-- upgrade-step: repo-prepare -->
```sh
cd <repo>
docket repository prepare
Expand All @@ -128,7 +117,6 @@ docket repository prepare
It reports `healthy` and keeps using the `.docket` folder Bash docket made. That does not mean the
repository is ready yet. The next command finds what still needs fixing.

<!-- upgrade-step: repo-check -->
```sh
docket repository check
```
Expand All @@ -149,7 +137,6 @@ On a Bash repository it exits with an error and lists some of these findings:
Start with `.gitignore`. Replace everything from its `# docket:start` line to its `# docket:end`
line with exactly these lines, which `docket repository check` also prints:

<!-- upgrade-step: fix-gitignore -->
```text
# docket:start (managed by docket — do not hand-edit)
.docket/
Expand All @@ -170,15 +157,13 @@ a warning, with a remedy. Remove each of them from `.docket.yml`. Section 6 list
that show up only as notices can stay. If the repository has no `.docket.yml`, there is nothing to
remove.

<!-- upgrade-step: config-cleanup -->
```sh
docket status
```

`docket status` reads `.docket.yml` from the pushed default branch, not from your working copy. Its
list clears only after you commit and push. Commit and push both files:

<!-- upgrade-step: commit-fixes -->
```sh
git commit -am "Update docket's .gitignore block and settings"
git push
Expand All @@ -187,7 +172,6 @@ git push
Now set up the test command. `docket repository configure-tests` writes the test settings into
`.docket.yml`. Review them.

<!-- upgrade-step: configure-tests -->
```sh
docket repository configure-tests
```
Expand All @@ -197,14 +181,12 @@ Next, choose the coding agents docket writes instructions for. On a terminal,
because Bash docket's `CLAUDE.md` block would get in the way. The last step of this section, after
you remove that block, chooses your agents.

<!-- upgrade-step: configure-harnesses -->
```sh
docket repository configure-harnesses --harnesses none
```

Commit and push both settings in `.docket.yml`, the test command and the agents:

<!-- upgrade-step: commit-config -->
```sh
git add .docket.yml
git commit -m "Configure docket's test command and agents"
Expand All @@ -214,22 +196,19 @@ git push
The last fix is for the records on the `docket` branch. First look at what will change: the command
lists the files it would rewrite and asks `repair? [y/N]`. Answer `N`.

<!-- upgrade-step: repair-preview -->
```sh
docket repository repair
```

Then apply the repairs. docket commits and pushes them to the `docket` branch itself, and brings
your local `.docket` folder up to the repaired commit.

<!-- upgrade-step: repair-apply -->
```sh
docket repository repair --yes
```

Then check the repository:

<!-- upgrade-step: repo-confirm -->
```sh
docket repository check
```
Expand All @@ -244,7 +223,6 @@ everything from the start line through the end line. If that leaves `CLAUDE.md`
file. Then commit and push the change. If there is no such block, skip this step.
There is nothing to commit, and `git commit` stops with an error.

<!-- upgrade-step: dispatch-block -->
```sh
git commit -am "Remove the Bash docket block from CLAUDE.md"
git push
Expand All @@ -256,7 +234,6 @@ For Cursor, it writes `.cursor/rules/docket-dispatch.mdc` into the repository, w
`.gitignore` block keeps out of commits. Drop the agent you don't use from `--harnesses`, and if you
don't use Claude Code, leave `CLAUDE.md` off the `git add` line.

<!-- upgrade-step: choose-harnesses -->
```sh
docket repository configure-harnesses --harnesses claude,cursor
git add .docket.yml CLAUDE.md
Expand All @@ -279,7 +256,7 @@ These are the Bash-era settings docket reports, in `.docket.yml` or in
| `build.checkpoint` | Error when set to `true`. | Remove it, or set it to `false`. |
| `auto_capture.enabled` | Error when set to `true`. | Remove it, or set it to `false`. |
| `dummy_mode.enabled` | Error when set to `true`. | Remove it, or set it to `false`. |
| `finalize.gate` | Error when set to `ci` or `both`. The saved installs cover `ci` only. | Remove it, or set it to `local` or `off`. |
| `finalize.gate` | Error when set to `ci` or `both`. | Remove it, or set it to `local` or `off`. |
| `board_surfaces` | Error when the list holds `github`. | Remove it, or remove `github` from the list. |
| `skills.<role>` | Error. | Remove it. |
| `agents.<harness>.<agent>.runner` | Error. | Remove it. |
Expand All @@ -292,14 +269,12 @@ These are the Bash-era settings docket reports, in `.docket.yml` or in
The Bash installer also left these behind. docket does not use them, and `docket install check`
does not mention them. Delete them:

<!-- upgrade-step: leftovers -->
```text
~/.claude/settings.json the "DOCKET_SCRIPTS_DIR" and "DOCKET_BASH_PATH" entries under "env"
~/.zshenv the lines from "# >>> docket (DOCKET_SCRIPTS_DIR) >>>" to "# <<< docket (DOCKET_SCRIPTS_DIR) <<<"
```

The test covers zsh, where those lines are in `~/.zshenv`. Other shells keep them in a different
startup file, which the test does not cover.
These lines are in `~/.zshenv` for zsh. Other shells keep them in a different startup file.

Your old Bash checkout, usually `~/dev/docket`, is no longer used by Claude Code or Cursor: nothing
under `~/.claude` or `~/.cursor` points into it after the upgrade. The links Bash docket made for
Expand All @@ -317,11 +292,8 @@ Bash docket also wrote agent files into a repository when its `.docket.yml` has
setting: one `docket-*.md` file per agent under the repository's `.claude/agents/` folder, and for
Cursor under `.cursor/agents/`. Claude Code uses an agent file in the repository instead of the one
with the same name in `~/.claude/agents/`, so these old files hide the agents the installer just
wrote. Delete them in every repository. If a repository has none, the command does nothing. The
saved installs the test runs carry no repository Cursor agent files, so the test does not prove the
`.cursor/agents` line.
wrote. Delete them in every repository. If a repository has none, the command does nothing.

<!-- upgrade-step: repo-agent-files -->
```sh
cd <repo>
rm -f .claude/agents/docket-*.md
Expand All @@ -334,8 +306,7 @@ commit.
In each repository it converted, Bash docket's `migrate-to-docket.sh` also wrote
`.claude/settings.local.json`. It holds a Claude Code permission rule for Bash docket's push to your
default branch, such as `Bash(git -C * push origin HEAD:main)`, and it can also hold settings of
your own. This guide does not cover that file: the test leaves it in place and does not show
whether deleting it is safe.
your own. This guide does not cover that file and does not say whether deleting it is safe.

## 8. Restart Claude Code and Cursor

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# Retire the saved Bash upgrade test cases — design

Change 0514 — Retire the saved Bash upgrade test cases when stable v1.0.0 ships

## Intent

`docs/release/upgrading-from-bash.md` moves a Bash docket `v0.9.2`/`v0.9.3` install to the docket
binary. During the v1.0.0 pre-releases, a test kept the guide accurate as the code changed: it
restored saved copies of real Bash installs from `testdata/bash-upgrade/` and ran the guide's
marked steps against the binary. Stable v1.0.0 has shipped, so that test has done its job. Users
never ran it, and it costs suite time on every build.

This change deletes the saved cases and everything that exists only for them. The guide stays,
edited so it describes only the upgrade, with no mention of a test that will no longer exist. The
human's rule: documentation must not keep referring to code that is gone.

## Goals

1. Remove the Bash upgrade proof and every artifact that exists only to support it.
2. Keep the one test in that package that is not about upgrades: the `dckt` alias check.
3. Leave the guide accurate after the removal: same steps, tables and commands, with every
sentence about "the test" gone or rewritten as the guide's own scope.

## Non-goals

- Changing any upgrade step, command, findings table, or the guide's structure.
- Changing the installer's v0.9.2 takeover behavior.
- Editing point-in-time records that mention the test: release `decisions.md` and
`candidate/run.txt` files, archived specs, plans and results, and the frozen export corpus under
`internal/export/testdata/corpus/`. They stay as written.

## Anti-goals

- Losing `TestAliasInvocationMatchesDocket` along with the package it happens to live in.
- Leaving a "last verified against v1.0.0" line or any other note pointing at the retired test.
The human explicitly rejected one.

## What gets deleted

- `testdata/bash-upgrade/` — the whole tree (`PROVENANCE.md`, `v0.9.2/`, `v0.9.3/`).
- `internal/bashupgrade/` — the whole package (`doc.go` and every `*_test.go`), after the alias
test is moved out (below).
- `tests/test_go_integration_bashupgrade.sh` — the integration shard (prefix
`TestIntegrationBashUpgrade`).
- The `tests/test_go_integration_bashupgrade.sh` row in `tests/runtime-budgets.tsv`.
- The `## Root \`testdata/bash-upgrade/<tag>/\`` section of `testdata/README.md`.

The builder re-runs a whole-repo grep for `bashupgrade`, `bash-upgrade`, `BashUpgrade` and
`upgrade-step` at build time and sorts each hit into maintained source (fix) or point-in-time
record (leave). At grooming time the only maintained hits were the items above and the guide.

## What moves

`TestAliasInvocationMatchesDocket` (currently `internal/bashupgrade/alias_invocation_test.go`)
checks that the binary invoked through a `dckt` symlink (`install.AliasName`) gives the same
`version --json` output as when invoked as `docket`. It sat in `internal/bashupgrade` only to reuse
that package's one-time binary build. Move it into the `cmd/docket` package, whose `TestMain`
(in `main_test.go`) already builds the binary once into `binPath`, so the move adds no build. The assertion stays the
same; only the binary source changes from `buildDocket(t)` to `binPath`.

## The guide edit (`docs/release/upgrading-from-bash.md`)

Each passage about the test, by the sentence it opens with today:

| Passage | Change |
|---|---|
| Intro: "An automated test runs every marked step below against saved copies…" (whole paragraph) | Delete. |
| §2: "The test covers repositories with no change in progress." | Becomes "The guide covers repositories with no change in progress." |
| §3: "The download and checksum lines are checked by the release's own verification, not by this guide's test." | Delete. Keep the "must print `install.sh: OK`" instruction before it. |
| §7: "The test covers zsh, where those lines are in `~/.zshenv`. Other shells keep them in a different startup file, which the test does not cover." | Becomes "These lines are in `~/.zshenv` for zsh. Other shells keep them in a different startup file." |
| §7: "The saved installs the test runs carry no repository Cursor agent files, so the test does not prove the `.cursor/agents` line." | Delete. |
| §7: "This guide does not cover that file: the test leaves it in place and does not show whether deleting it is safe." | Becomes "This guide does not cover that file and does not say whether deleting it is safe." |
| All 20 `<!-- upgrade-step: <name> -->` marker comments | Delete. |

These are the passages found at grooming time. The builder greps the guide for `test` once more
and applies the same rule to any other sentence about the retired test: delete it if it only
describes test coverage, or rewrite it as the guide's own scope if the limit still matters to a
reader. The links to the guide from `README.md` and `docs/install/install.md` stay.

## Verification

- The full suite passes (`build.test_command`). The budget runner no longer lists the deleted shard,
and no runtime-budgets row is orphaned.
- `TestAliasInvocationMatchesDocket` runs in the `cmd/docket` package and passes. As a mutation
check, break the comparison and confirm the test goes red.
- The whole-repo grep above returns only point-in-time records.

## Left to the builder

- The exact wording around the deleted sentences, as long as no step, command or table changes.
- Whether the moved alias test keeps its own file in `cmd/docket` or joins `main_test.go`.
Loading
Loading