Document command signature contribution workflow

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/<command>.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/<Cmdlet>.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/<path>.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.