Contributing

How to report bugs, propose changes, write commits and pull requests, and record decisions.

Wingsmith is pre-release and maintained by a small team, so the process is light. If something here is unclear or gets in your way, open an issue about that too.

Everyone taking part is expected to follow the Code of Conduct in the repository.

Before you commit

Run git config core.hooksPath .githooks once per clone to enable the pre-commit and commit-msg hooks. Run just check before you open a pull request; the commands it runs are listed under Checks.

Commits

• Small and logical. One behaviour change per commit, with its tests in the same commit or the one right after it.
• Subject style. A lowercase conventional type and scope, then a full sentence saying what changed in behaviour, not which files were touched.
• The body explains why, when the subject cannot. Link the issue if there is one.
• Nothing generated or private. Do not commit generated files, local configuration, credentials or real hostnames. The pre-commit hook runs a leak check, and gitleaks if it is installed. CI runs both.

fix(plane): refuse a metrics window that is not a plain duration
feat(console): show the deployment's admission reason on the workload page
docs: describe the gateway's cold-start dependency on the plane
test(gateway): pin that a tenant's model on another host reads as 404

Code conventions

The formatters and linters are the style guide. just fmt and just lint settle most questions. Beyond them:

Architecture decision records

Decisions that shape the system are recorded in docs/decisions/ in the repository. Architecture decisions summarises them.

• Add one when a change picks between real alternatives, changes the object model or the wire, or reverses an earlier record.
• Name it NNNN-the-decision-as-a-sentence.md, with the next free number. Copy an existing record: a **Status:** line (proposed, accepted, superseded by NNNN), then Context, Decision and Consequences.
• An accepted record is not rewritten. A later decision that changes it gets its own record, and the old one gains an “amended by” or “superseded by” note pointing at it.
• Propose an ADR in the same pull request as the change it records, or on its own first if the design needs agreeing before the code.

Pull requests

• Keep a pull request to one concern. Several small ones review faster than one large one.
• Describe what changed in behaviour and how you checked it. The template asks for this.
• Add or update tests for every behaviour change, and update the README or docs a change makes wrong.
• CI must be green: format, lint and tests for every module, the database suite and the leak checks.
• A maintainer reviews every pull request (see .github/CODEOWNERS). Expect questions about why, not just what; the answers often belong in the commit message.
• Maintainers merge. History on main is kept as committed, so a clean series of commits matters more than one squashed commit.

How this code is written

Much of the code was written with AI coding assistants, under a single maintainer. The history before the public release was not reviewed by a second person. The test suites were the main check on it, and they still are. From here on, changes arrive as pull requests that CI tests and a maintainer reviews, whoever or whatever wrote them.

License

By contributing you agree that your contributions are licensed under the Apache License 2.0. The project name and logo are covered separately by TRADEMARKS.md in the repository.