Skip to content

revert(hooks): keep docs on pre-start/post-start; code accepts both - #2857

Merged
max-sixty merged 1 commit into
mainfrom
revert-hook-rename-docs
May 21, 2026
Merged

max-sixty merged 1 commit into
mainfrom
revert-hook-rename-docs

Conversation

@worktrunk-bot

Copy link
Copy Markdown
Collaborator

Per @max-sixty's direction in #2838: revert the docs portion of #2840 and keep the code. Docs continue to recommend pre-start/post-start; both names work in code so anyone who already followed the briefly-changed docs (e.g. @EcksDy) isn't stranded once a release ships these aliases.

User-visible — back to pre-start/post-start

  • README, docs site, skill mirrors, dev/*.example.toml, plugins/worktrunk/README.md, flake.nix, .config/wt.toml
  • src/cli/mod.rs / src/cli/config.rs / src/cli/step.rs / src/help.rs after_long_help and example snippets — and the auto-synced docs/content/ and skills/worktrunk/reference/ mirrors
  • wt hook --help canonical subcommand names; completion advertises -start only
  • HookType Display via strum, serde rename, and clap ValueEnum name — all pre-start/post-start. The Rust variant identifiers stay PreCreate/PostCreate (internal; we already paid for that rename in feat(hooks): rename worktree-creation hooks to pre-create/post-create #2840, and now the eventual flip is a Display-only change)
  • HooksConfig serde canonical fields

*-create still works (kept code)

  • wt hook pre-create / post-create — CLI alias on the canonical subcommand
  • pre-create / post-create in config: top-level, [hooks.*], and per-project, in string, [table], and [[array-of-tables]] form. Mechanism: serde alias = ... on the field, plus a silent in-memory rename in migrate_content() so the round-trip in unknown_tree doesn't flag table forms as schema-unknown.
  • The pre-0.32.0 post-create fatal-load-error machinery stays removed — the name is reclaimed, and both forms load without error.

Smaller bits

  • valid_user_config_keys() / valid_project_config_keys() append pre-create / post-create so the unknown-field round-trip skips them. test_valid_*_keys_all_deserialize skips both aliases (they can't sit alongside the canonical without a duplicate-field error).
  • DEPRECATED_SECTION_KEYS drops the pre-start/post-start entries feat(hooks): rename worktree-creation hooks to pre-create/post-create #2840 added — pre-start/post-start are canonical again.
  • find_pre_start_from_doc / find_post_start_from_doc / find_renamed_hook_key / is_non_empty_item / migrate_start_hooks_doc and their tests are removed; the migration direction flips via a new migrate_create_hooks_doc (silent, mirrors the prior shape).
  • Test files e2e_shell_post_create.rs and post_create_commands.rs rename back to _post_start_ (via git mv, so the rename shows as a rename).

Testing

cargo run -- hook pre-merge --yes — 3806 tests pass; the 10 failures are all case_4 of shell_wrapper::unix_tests::* (nu-shell case; nu isn't installed in this runner; same failures occur on main).

Also manually verified that a fresh wt switch --create against a project config with [post-create] loads cleanly with no unknown-field warning and the hook fires as post-start.

Follow-up

Per @max-sixty: in a couple of weeks, once a release with both-names-work is out and users have had a chance to upgrade, the docs flip is straightforward (most of it is in src/cli/mod.rs's after_long_help and the doc-sync test propagates).

Re #2838.

Reverts the docs portion of #2840 (pre-start/post-start → pre-create/post-create
rename, Phase 1) while keeping the code change so both names continue to work.
Per #2838 discussion, docs continue to recommend the original names until users
have updated to a version that accepts both — preventing the experience reported
in the issue where docs advised post-create on a version that still rejects it.

What stays user-visible as pre-start/post-start:

- README, docs site, skill mirrors, dev/*.example.toml, plugins/, flake.nix
- src/cli/mod.rs / src/cli/config.rs / src/cli/step.rs / src/help.rs and the
  generated command-page mirrors
- wt hook --help canonical subcommand names; completion advertises -start only
- Strum / serde / clap-ValueEnum canonical Display for HookType is `*-start`;
  the Rust variant names `PreCreate`/`PostCreate` stay (internal-only, paid for
  in the original rename; the eventual flip becomes a Display-only change)
- HooksConfig serde field rename canonical is `pre-start`/`post-start`

What still works from `*-create` (kept code):

- `wt hook pre-create` / `post-create` (CLI alias on the canonical subcommand)
- `pre-create` / `post-create` in config (top-level, [hooks.*], and per-project
  in string, table, and array-of-tables form) via serde `alias = ...` on the
  field, plus a silent in-memory rename in `migrate_content()` so the unknown-
  key round-trip in `unknown_tree` doesn't flag table forms as schema-unknown.
- The pre-0.32.0 `post-create` fatal-load-error machinery stays removed — the
  name is reclaimed and both forms load.

Notes:

- `valid_user_config_keys()` / `valid_project_config_keys()` append the two
  aliases so the unknown-field warning skips them. `test_valid_*_keys_all_
  deserialize` skips both aliases (can't sit alongside the canonical without
  a duplicate-field error).
- `DEPRECATED_SECTION_KEYS` drops the `pre-start`/`post-start` entries that the
  original PR added; deprecation warnings stay silent for hook renames (this
  was already the policy — Phase 2 was months out).
- The `find_pre_start_from_doc` / `migrate_start_hooks_doc` / `snapshot_
  migrate_start_to_create` helpers and tests are removed; the migration
  direction flips via the new `migrate_create_hooks_doc`.

Re #2838 thread; closes the immediate confusion reported by @EcksDy.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@max-sixty
max-sixty enabled auto-merge (squash) May 21, 2026 15:57
@max-sixty
max-sixty merged commit ec62580 into main May 21, 2026
33 of 34 checks passed
@max-sixty
max-sixty deleted the revert-hook-rename-docs branch May 21, 2026 16:03

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Self-review on a bot PR — read it sceptically.

The mechanical pre-create/post-create → pre-start/post-start text replacement broke several alias-direction tests. After this revert the canonical name is pre-start and the alias is pre-create, but multiple tests still write [pre-start]/[post-start] in the fixture TOML and only assert against pre-start/post-start on the CLI — so they exercise neither the load-time migration nor the value-parser alias. Two of them have inline fixes below; the rest need broader rework (doc comment, function name, fixture TOML) and I'd rather leave that to the author than commit something half-converted.

Tests that need follow-up beyond the inline suggestions:

  • tests/integration_tests/config_show.rs:365-413 — the doc comment ("uses the deprecated pre-start/post-start hook keys keeps working… migrates the keys to pre-start/post-start"), the function name test_hook_show_accepts_deprecated_start_hooks, the inline comment about -create arg / -start arg (lines 384-386), and the [pre-start]/[post-start] fixture all describe the old direction. To exercise the new alias the fixture should use [pre-create]/[post-create] and the cases array should test both names on the CLI side (the inline suggestion below covers the cases-array half).
  • tests/integration_tests/post_start_commands.rs:63-103 — test_deprecated_start_hook_key_runs_silently writes pre-start = "…" (canonical), comments say "deprecated pre-start hook key… silently migrated to pre-start", assertion message says "deprecated pre-start hook should have run". No alias is exercised. If the intent is still to cover the alias direction, fixture should be pre-create = "…".
  • tests/integration_tests/user_hooks.rs:1594-1621 — test_standalone_hook_start_alias_runs_silently doc-comments itself as "wt hook pre-start is a deprecated alias for wt hook pre-start" (self-referential), config writes pre-start, CLI invokes wt hook pre-start. To test the new alias direction this should write pre-create (config) or invoke wt hook pre-create (CLI).

Other follow-ups:

  • src/commands/hook_commands.rs:385 — comment says "canonical name or deprecated -start alias"; the alias is now -create.
  • src/config/deprecation.rs:1572-1573 (outside this diff, but the reason the line is wrong is this revert) — "Some deprecations migrate silently (e.g. the -start → -create hook rename)"; direction is now reversed.
  • The five unit tests for migrate_start_hooks_doc in src/config/deprecation.rs (test_find_start_hook_deprecation_*, test_migrate_start_hooks_skips_when_create_exists, snapshot_migrate_start_to_create) were removed but no equivalents added for migrate_create_hooks_doc. The new direction's edge cases (skip when canonical already exists, [projects."…"] table form, array-of-tables) now have no unit coverage — only the integration suite would catch a regression.
  • src/config/deprecation.rs:479-481 — Deprecations::pre_start / post_start are kept as pub fields that are always false. Per CLAUDE.md's "Don't suppress warnings" rule that's either a delete-and-re-add when the flip happens, or a // TODO(#2838): reused when the direction flips comment so the intent isn't lost in the "always false" docstring.

Not a blocker: I can't approve a self-authored PR; flagging so a maintainer can decide whether to land as-is or want the test follow-up first.

Comment on lines +389 to +390
("pre-start", "pre-start-tool"),
("post-start", "post-start-tool"),

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two new entries duplicate the lines above and below, so the cases array exercises only pre-start/post-start (the canonical names) — never the pre-create/post-create alias the PR is adding. Replace them so the second case in each pair tests the alias path:

Suggested change
("pre-start", "pre-start-tool"),
("post-start", "post-start-tool"),
("pre-create", "pre-start-tool"),
("post-create", "post-start-tool"),

This half-fixes the test; the surrounding doc comment, function name, inline comment (lines 384-386), and fixture TOML (lines 376-381) still describe the pre-revert direction and need updating too — see the review body for the full list.

assert!(
stdout.contains("npm install"),
"post-start in system config should migrate to post-create and stay active, got: {stdout}"
"post-start in system config should migrate to post-start and stay active, got: {stdout}"

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After the revert post-start is canonical, so this is self-referential — there's no migration to assert. The assertion is just "the configured hook loads and stays active":

Suggested change
"post-start in system config should migrate to post-start and stay active, got: {stdout}"
"post-start in system config should load and stay active, got: {stdout}"

(If the goal is still to exercise the post-create alias here, the fixture on line 655 needs to be post-create = "npm install" and this message should reflect that — the surrounding context already tests [select] deprecation handling, which is the main point of the test.)

max-sixty added a commit that referenced this pull request May 22, 2026
Follow-up to #2857. That PR reverted the docs half of the
`pre-start`/`post-start` → `pre-create`/`post-create` hook rename while
keeping the code that accepts both names. Its self-review landed 26
seconds after the merge, so none of its findings were addressed —
several tests still described the pre-revert direction and exercised
only canonical names, so they would pass even if the deprecated alias
broke.

## Changes

The three deprecated-alias tests now use `pre-create`/`post-create` in
their fixtures (or invoke `wt hook pre-create`), so they exercise the
migration and the CLI alias rather than canonical names:
`test_hook_show_accepts_deprecated_create_hooks`,
`test_deprecated_create_hook_key_runs_silently`,
`test_standalone_hook_create_alias_runs_silently`.

`test_parse_hook_type_aliases` had the same defect — it parsed only the
canonical names — and now parses both forms and asserts they map to the
same `HookType`.

Added unit tests for `migrate_create_hooks_doc` (every value shape,
per-project tables, skip-when-canonical-exists, invalid TOML) plus a
migration-diff snapshot; the revert removed the
`migrate_start_hooks_doc` tests with no equivalent.

Deleted `Deprecations::pre_start`/`post_start` — always-false dead
fields once the revert removed their detection.

Deleted `test_config_show_displays_start_hook_migration`: post-revert
there is no detection for `pre-create`, so `wt config show` shows no
migration diff and the test verified nothing (its regenerated snapshot
confirmed this).

Also corrected reversed-direction comments in `deprecation.rs` and
`hook_commands.rs`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
max-sixty added a commit that referenced this pull request May 23, 2026
Two small follow-ups noticed while fixing the test comments in #2877.

**`pre_create` docstring was wrong.** It read "Commands to execute
before worktree creation (blocking)", but `pre-start` actually runs
*after* the worktree is created (`switch.rs:1142` executes it against
"the new worktree (created just above)", and the renamed test below
asserts the worktree exists after a failing pre-start). The wrong
wording entered in #2840 as part of the mechanical `pre-start` →
`pre-create` rename — someone "corrected" the docstring to match the new
name. #2857 reverted the name but left the docstring. Restoring "after
worktree creation (blocking, fail-fast)" matches the actual behavior,
`docs/content/hook.md` ("Runs once when a new worktree is created,
blocking…"), and the parallel `post_create` docstring. Because
`HooksConfig` derives `JsonSchema`, this docstring is user-visible in
generated schema descriptions.

**`test_user_post_start_hook_failure` was misnamed.** The fixture is
`[pre-start]`, the comment and assertion describe a failing pre-start,
and only the function name said post-start. Renamed to
`test_user_pre_start_hook_failure` along with its snapshot name and file
(`git mv`, so the rename shows as a rename).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
max-sixty pushed a commit that referenced this pull request May 23, 2026
…2857)

Per @max-sixty's [direction in
#2838](#2838 (comment)):
revert the docs portion of #2840 and keep the code. Docs continue to
recommend `pre-start`/`post-start`; both names work in code so anyone
who already followed the briefly-changed docs (e.g. @EcksDy) isn't
stranded once a release ships these aliases.

## User-visible — back to `pre-start`/`post-start`

- README, docs site, skill mirrors, `dev/*.example.toml`,
`plugins/worktrunk/README.md`, `flake.nix`, `.config/wt.toml`
- `src/cli/mod.rs` / `src/cli/config.rs` / `src/cli/step.rs` /
`src/help.rs` after_long_help and example snippets — and the auto-synced
`docs/content/` and `skills/worktrunk/reference/` mirrors
- `wt hook --help` canonical subcommand names; completion advertises
`-start` only
- `HookType` Display via strum, serde `rename`, and clap `ValueEnum`
name — all `pre-start`/`post-start`. The Rust variant identifiers stay
`PreCreate`/`PostCreate` (internal; we already paid for that rename in
#2840, and now the eventual flip is a Display-only change)
- `HooksConfig` serde canonical fields

## `*-create` still works (kept code)

- `wt hook pre-create` / `post-create` — CLI alias on the canonical
subcommand
- `pre-create` / `post-create` in config: top-level, `[hooks.*]`, and
per-project, in string, `[table]`, and `[[array-of-tables]]` form.
Mechanism: serde `alias = ...` on the field, plus a silent in-memory
rename in `migrate_content()` so the round-trip in `unknown_tree`
doesn't flag table forms as schema-unknown.
- The pre-0.32.0 `post-create` fatal-load-error machinery stays removed
— the name is reclaimed, and both forms load without error.

## Smaller bits

- `valid_user_config_keys()` / `valid_project_config_keys()` append
`pre-create` / `post-create` so the unknown-field round-trip skips them.
`test_valid_*_keys_all_deserialize` skips both aliases (they can't sit
alongside the canonical without a duplicate-field error).
- `DEPRECATED_SECTION_KEYS` drops the `pre-start`/`post-start` entries
#2840 added — `pre-start`/`post-start` are canonical again.
- `find_pre_start_from_doc` / `find_post_start_from_doc` /
`find_renamed_hook_key` / `is_non_empty_item` /
`migrate_start_hooks_doc` and their tests are removed; the migration
direction flips via a new `migrate_create_hooks_doc` (silent, mirrors
the prior shape).
- Test files `e2e_shell_post_create.rs` and `post_create_commands.rs`
rename back to `_post_start_` (via `git mv`, so the rename shows as a
rename).

## Testing

`cargo run -- hook pre-merge --yes` — 3806 tests pass; the 10 failures
are all `case_4` of `shell_wrapper::unix_tests::*` (nu-shell case; `nu`
isn't installed in this runner; same failures occur on `main`).

Also manually verified that a fresh `wt switch --create` against a
project config with `[post-create]` loads cleanly with no unknown-field
warning and the hook fires as `post-start`.

## Follow-up

Per @max-sixty: in a couple of weeks, once a release with
both-names-work is out and users have had a chance to upgrade, the docs
flip is straightforward (most of it is in `src/cli/mod.rs`'s
`after_long_help` and the doc-sync test propagates).

Re #2838.

Co-authored-by: worktrunk-bot <254187624+worktrunk-bot@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
max-sixty added a commit that referenced this pull request May 23, 2026
Follow-up to #2857. That PR reverted the docs half of the
`pre-start`/`post-start` → `pre-create`/`post-create` hook rename while
keeping the code that accepts both names. Its self-review landed 26
seconds after the merge, so none of its findings were addressed —
several tests still described the pre-revert direction and exercised
only canonical names, so they would pass even if the deprecated alias
broke.

## Changes

The three deprecated-alias tests now use `pre-create`/`post-create` in
their fixtures (or invoke `wt hook pre-create`), so they exercise the
migration and the CLI alias rather than canonical names:
`test_hook_show_accepts_deprecated_create_hooks`,
`test_deprecated_create_hook_key_runs_silently`,
`test_standalone_hook_create_alias_runs_silently`.

`test_parse_hook_type_aliases` had the same defect — it parsed only the
canonical names — and now parses both forms and asserts they map to the
same `HookType`.

Added unit tests for `migrate_create_hooks_doc` (every value shape,
per-project tables, skip-when-canonical-exists, invalid TOML) plus a
migration-diff snapshot; the revert removed the
`migrate_start_hooks_doc` tests with no equivalent.

Deleted `Deprecations::pre_start`/`post_start` — always-false dead
fields once the revert removed their detection.

Deleted `test_config_show_displays_start_hook_migration`: post-revert
there is no detection for `pre-create`, so `wt config show` shows no
migration diff and the test verified nothing (its regenerated snapshot
confirmed this).

Also corrected reversed-direction comments in `deprecation.rs` and
`hook_commands.rs`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
max-sixty added a commit that referenced this pull request May 23, 2026
Two small follow-ups noticed while fixing the test comments in #2877.

**`pre_create` docstring was wrong.** It read "Commands to execute
before worktree creation (blocking)", but `pre-start` actually runs
*after* the worktree is created (`switch.rs:1142` executes it against
"the new worktree (created just above)", and the renamed test below
asserts the worktree exists after a failing pre-start). The wrong
wording entered in #2840 as part of the mechanical `pre-start` →
`pre-create` rename — someone "corrected" the docstring to match the new
name. #2857 reverted the name but left the docstring. Restoring "after
worktree creation (blocking, fail-fast)" matches the actual behavior,
`docs/content/hook.md` ("Runs once when a new worktree is created,
blocking…"), and the parallel `post_create` docstring. Because
`HooksConfig` derives `JsonSchema`, this docstring is user-visible in
generated schema descriptions.

**`test_user_post_start_hook_failure` was misnamed.** The fixture is
`[pre-start]`, the comment and assertion describe a failing pre-start,
and only the function name said post-start. Renamed to
`test_user_pre_start_hook_failure` along with its snapshot name and file
(`git mv`, so the rename shows as a rename).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants