mirror of
https://github.com/instructkr/claude-code.git
synced 2026-05-27 16:06:44 +00:00
25ee5f3d30
Add a lightweight ROADMAP duplicate-id guard and wire it into the low-risk docs/pre-push paths so optimistic append collisions introduced after the next-id helper are caught before merge. Constraint: Current ROADMAP contains legacy numbered lists and pre-helper duplicate low ids, so the default guard checks helper-era ids >=723 while preserving --min-id 1 for a future strict audit. Rejected: Fail CI on every numeric duplicate in the whole historical ROADMAP | current main would fail before this PR because old prose/list numbering is already duplicated. Confidence: high Scope-risk: narrow Directive: Keep roadmap-next-id.sh paired with roadmap-check-ids.sh when changing ROADMAP append workflows. Tested: bash -n scripts/roadmap-check-ids.sh scripts/roadmap-next-id.sh .github/hooks/pre-push; scripts/roadmap-check-ids.sh; temp ROADMAP copy with duplicate 723 failed nonzero and listed id 723; SKIP_CLAW_PRE_PUSH_BUILD=1 .github/hooks/pre-push; git diff --check; python3 .github/scripts/check_doc_source_of_truth.py; python3 .github/scripts/check_release_readiness.py Not-tested: full cargo workspace build/test because this is docs/scripts-only and the local pre-push cargo build was smoke-tested with its documented skip path.
102 lines
3.2 KiB
Markdown
102 lines
3.2 KiB
Markdown
# Contributing to Claw Code
|
|
|
|
Thanks for helping improve Claw Code. This repository is a Rust-first CLI
|
|
workspace with supporting docs and compatibility fixtures.
|
|
|
|
## Ground rules
|
|
|
|
- Keep changes small, reviewable, and tied to a concrete issue or behavior.
|
|
- Do not commit secrets, API keys, session transcripts with credentials, or
|
|
generated build output.
|
|
- Prefer existing crate boundaries and utilities before adding dependencies.
|
|
- Update documentation when a user-facing command, config key, or provider
|
|
behavior changes.
|
|
- Keep examples copy/paste safe. Use placeholder keys such as `sk-ant-...` and
|
|
avoid commands that require live credentials unless the text explicitly says
|
|
so.
|
|
|
|
## Local setup
|
|
|
|
```bash
|
|
git clone https://github.com/ultraworkers/claw-code
|
|
cd claw-code/rust
|
|
cargo build --workspace
|
|
cargo test --workspace
|
|
```
|
|
|
|
On Windows PowerShell, build from the same `rust` workspace and run the binary
|
|
with the `.exe` suffix:
|
|
|
|
```powershell
|
|
cd claw-code\rust
|
|
cargo build --workspace
|
|
.\target\debug\claw.exe --help
|
|
```
|
|
|
|
## Local pre-push build gate
|
|
|
|
Install the repository-local hook to catch stale compile errors before pushing:
|
|
|
|
```bash
|
|
git config core.hooksPath .github/hooks
|
|
```
|
|
|
|
This sets the repo's Git hook directory to `.github/hooks`; if you already use a
|
|
custom `core.hooksPath`, copy or chain `.github/hooks/pre-push` instead. The hook
|
|
runs the ROADMAP id guard, then runs
|
|
`cargo build --manifest-path rust/Cargo.toml --workspace --locked` from the
|
|
repository root. If you must bypass the cargo build for a docs-only push, set
|
|
`SKIP_CLAW_PRE_PUSH_BUILD=1`; the hook still runs the ROADMAP guard and prints
|
|
when the cargo-build escape hatch is used.
|
|
|
|
## ROADMAP id allocation
|
|
|
|
Before appending a new numeric ROADMAP entry, pull/rebase onto the latest
|
|
`main`, allocate the id from the file you are about to edit, and run the duplicate
|
|
id guard before pushing:
|
|
|
|
```bash
|
|
git pull --rebase
|
|
NEXT=$(scripts/roadmap-next-id.sh)
|
|
# append "${NEXT}. **...**" to ROADMAP.md
|
|
scripts/roadmap-check-ids.sh
|
|
```
|
|
|
|
The duplicate guard currently checks helper-era ids (`>=723`) by default so it
|
|
catches new optimistic-append collisions without failing on legacy numbered lists
|
|
already present in the historical roadmap. Use `scripts/roadmap-check-ids.sh
|
|
--min-id 1` for a strict whole-file audit after those legacy collisions are
|
|
cleaned up.
|
|
|
|
## Checks before opening a pull request
|
|
|
|
Run the smallest relevant tests for your change, then the broader checks when
|
|
you touch shared runtime, CLI, or docs surfaces:
|
|
|
|
```bash
|
|
cd rust
|
|
cargo fmt --all --check
|
|
cargo test --workspace
|
|
cargo clippy --workspace
|
|
```
|
|
|
|
For documentation and release-readiness changes, also run:
|
|
|
|
```bash
|
|
python .github/scripts/check_doc_source_of_truth.py
|
|
python .github/scripts/check_release_readiness.py
|
|
```
|
|
|
|
## Pull request guidance
|
|
|
|
- Describe the user-visible reason for the change.
|
|
- List the commands you ran and any known gaps.
|
|
- Call out compatibility risks for CLI output, JSON schemas, plugin contracts,
|
|
provider behavior, or Windows/PowerShell examples.
|
|
- Keep unrelated cleanup out of feature or fix pull requests.
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions are licensed under the
|
|
project's [MIT License](./LICENSE).
|