diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5dc69ff --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to any2bazel + +Contributions are welcome. This document explains how to contribute and which +checks must pass before a change can merge. + +## EngFlow CLA + +All contributions require a signed EngFlow Contributor License Agreement (CLA) +on file before they can be merged. If you have not signed one, a maintainer +will let you know how to do so when you send your first change. + +## Discuss major changes first + +For anything larger than a small fix, please reach out and discuss the change +with the maintainers before investing significant effort. Open an issue at +https://github.com/EngFlow/any2bazel describing the problem and your proposed +approach. This avoids duplicated work and changes that don't fit the project's +direction. + +## Changes must be complete + +Each change should be a complete solution: + +* Changes to `scripts/` must include tests in `tests/`. +* Changes to a script's arguments, output, or behavior must update `SKILL.md` + and any affected documentation in the same change. +* Bug fixes should include a test that fails without the fix. + +Keep changes focused, smaller changes ensure faster reviews. + +## Code style +Python code in this project generally follows [PEP +8](https://peps.python.org/pep-0008/). When in doubt, follow the style of the +surrounding code. + +## Sending changes + +Send changes as pull requests to https://github.com/EngFlow/any2bazel. Make +sure all presubmit requirements below pass. + +## Presubmit requirements + +### Python tests + +CI runs the test suite with pytest in a fresh virtual environment. To +reproduce locally: + +```bash +python -m venv .venv +.venv/bin/pip install pytest +.venv/bin/pytest tests/ +``` + +### Copyright headers + +All source files must begin with the Apache 2.0 license header. + +```bash +bazel run //infra/internal/check_copyright_headers +``` + +> [!IMPORTANT] +> The check inspects files in `HEAD`, not the working tree. **Commit your +> changes before running it**, or new files will not be checked. diff --git a/README.md b/README.md index ef26786..ba8636b 100644 --- a/README.md +++ b/README.md @@ -74,8 +74,9 @@ deterministic diff drives the loop — an LLM does only the creative work ## Contributing -Contributions are welcome. Please send any feedback and changes to the main -repo at https://github.com/EngFlow/any2bazel. +Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for +contribution flows and requirements. Please send any feedback and changes to the +main repo at https://github.com/EngFlow/any2bazel. [license]: https://img.shields.io/badge/license-Apache%202.0-blue.svg [license-url]: LICENSE diff --git a/SKILL.md b/SKILL.md index fa05f5e..9dd1fdd 100644 --- a/SKILL.md +++ b/SKILL.md @@ -186,10 +186,10 @@ flags. Tests are opt-in (`include_tests`) and get the compile-parity stage only ## Procedure -> **Script paths vs. project paths.** The `scripts/…` and `tests/…` paths below -> are relative to **this skill's own directory** (where this `SKILL.md` lives) — -> NOT the project being migrated. When running inside a target repo, invoke them -> by absolute path, e.g. +> **Script paths vs. project paths.** The `scripts/…` paths below are relative +> to **this skill's own directory** (where this `SKILL.md` lives) — NOT the +> project being migrated. When running inside a target repo, invoke them by +> absolute path, e.g. > `python3 "$SKILL_DIR/scripts/extract_cmake.py" …` where `$SKILL_DIR` is this > skill's install location (e.g. `~/.claude/skills/any2bazel`). The artifacts > you *produce* — `model.*.json`, `aquery.json`, `diff.json`, the generated @@ -399,16 +399,8 @@ build brings (no action graph to extract, traversal-order-dependent output, `node_modules` as both toolchain and foreign Bazel package): [docs/CASE-vscode-migration.md](docs/CASE-vscode-migration.md). -## Tests +## Updating this skill -```bash -python3 tests/test_engine.py && python3 tests/test_extractors.py \ - && python3 tests/test_maven.py && python3 tests/test_extract_npm.py \ - && python3 tests/test_triage.py && python3 tests/test_configure.py -``` - -Extractor tests run against fixtures that mirror the documented File API, -aquery, Maven argfile, and npm-NDJSON schemas. When a real project surfaces a -schema detail the extractors mishandle (fragment quoting, `external/` repo paths -in aquery, multi-config), fix the extractor and capture that output as a new -fixture. +To change this skill or its scripts, read +[CONTRIBUTING.md](CONTRIBUTING.md) first. It covers testing and presubmit +requirements.