From d088f949d2de39a8cafe4127374648389531a614 Mon Sep 17 00:00:00 2001 From: "warp-factories[bot]" <243557089+warp-factories[bot]@users.noreply.github.com> Date: Fri, 4 Sep 2026 00:58:47 +0000 Subject: [PATCH] Document command signature contribution workflow Adds a 'Contributing command signatures' section to README.md covering how to choose between a handwritten signature, a PowerShell-generated signature, and a persistent override; the format/regenerate/validate command sequence; and a pre-PR checklist. Also corrects the override docs, which claimed only `template` is supported, when command-signatures/src/overrides.rs supports both `template` and `generatorName`. Implements the workflow specified in #397. Closes #396 --- README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 02a80aba..fa944c68 100644 --- a/README.md +++ b/README.md @@ -56,9 +56,64 @@ Options are therefore matched by the `OptionOverrides::name` field and positiona ``` **Note:** Overrides for all fields on `fig_types::{Arg, Option}` may not be implemented yet. -At the time of writing, _only_ `template` is supported. +At the time of writing, `template` and `generatorName` are supported, for both top-level positional arguments and option arguments. Others will need to be added as needed. +## Contributing command signatures + +This section walks through the end-to-end workflow for changing a command signature: choosing the right file, formatting it, regenerating derived output when needed, and validating the change before opening a pull request. + +### Choose the signature source + +1. **Handwritten signature** — use `command-signatures/json/.json` for a command that isn't PowerShell-generated. Every top-level JSON file in `command-signatures/json` is handwritten. +2. **PowerShell-generated signature** — files under `command-signatures/json/autogenerated/powershell/*.json` are generated output. Never edit them directly; your changes will be overwritten the next time the generator runs. Instead, change `command-signatures/src/bin/autogenerate_powershell.rs` (or its supporting conversion code) and regenerate. +3. **PowerShell override** — use `command-signatures/json/overrides/powershell/.json` for a persistent, per-cmdlet `template` or `generatorName` adjustment that the PowerShell source data doesn't provide (see [Overriding Autogenerated Commands](#overriding-autogenerated-commands) above). An override is an input to generation, not a runtime patch, so it must be applied by rerunning the generator. + +### Format and regenerate + +1. Install Node dependencies if you haven't already: `npm ci`. +2. Format the JSON you changed (handwritten signatures or overrides): + + ```sh + npm run format -- command-signatures/json/.json + ``` + + You can also run `npm run format` to format all non-ignored signature JSON, or `npm run format:check` to check formatting without writing changes. Don't run Prettier over `command-signatures/json/autogenerated/`; `.prettierignore` excludes it because the generator owns that output's serialization. +3. Rerun `cargo run --bin autogenerate_powershell` whenever any of the following is true: + - you changed the PowerShell autogeneration logic or its supporting conversion code; + - you changed a file under `command-signatures/json/overrides/powershell/`; + - you're intentionally refreshing generated output for an upstream PowerShell cmdlet/help/metadata change. + + When regeneration changes files under `command-signatures/json/autogenerated/powershell/`, inspect the diff to confirm it's limited to the cmdlets and fields you expect, and keep the generated changes in a separate commit from the source change (generator or override) that caused them. Don't hand-edit generated output to hide or repair unexpected results — investigate broad or unexpected churn instead, since the generator depends on the PowerShell metadata available in your local environment and isn't pinned to a specific version. + +### Validate the change + +Run the full local validation suite from the repository root before opening a pull request: + +```sh +script/presubmit +``` + +This runs, in order: + +- `npm run format:check`; +- `cargo fmt -p warp-command-signatures -p warp-completion-metadata --check`; +- `cargo clippy -p warp-command-signatures -p warp-completion-metadata --all-targets --all-features -- -D warnings`; +- `cargo test --verbose`. + +Note that `script/presubmit` validates the checked-in output; it does not run the PowerShell generator, so regenerating is your responsibility whenever it's required (see above). Pull-request CI (`.github/workflows/CI.yml`) mirrors these same format, lint, and test checks. + +### Before opening a pull request + +- [ ] The change is in the correct handwritten, autogenerated, or override location. +- [ ] No generated PowerShell file was edited directly. +- [ ] Changed JSON was formatted with the repository's `npm run format` command. +- [ ] `cargo run --bin autogenerate_powershell` was rerun whenever a generator input changed. +- [ ] Any resulting generated diff is expected, reviewed, and isolated in a separate commit. +- [ ] The signature or override describes the intended command, arguments, options, templates, and generators. +- [ ] `script/presubmit` passes from the repository root. +- [ ] The pull request description explains whether it contains handwritten, generator, override, or regenerated changes. + ## License This project is licensed under the MIT License. See the LICENSE file for details. Many of the signatures were adapted from Fig (https://github.com/withfig/autocomplete), which is also licensed under the MIT License.