--- status: active period: ongoing theme: buildchain-contributing doc_type: process-rule source_level: local-files confidence: high sensitivity: public evidence_grade: B review_state: unreviewed last_reviewed: 2026-09-23 ai_provenance: model_family: GPT-6 product: Codex generated_at: 2026-09-23 visible_context: Repository contribution rules and implementation naming and release transition changes. invisible_context_boundary: No private credentials or unpublished external release state. --- # Contributing to Buildchain Thanks for your interest in Buildchain. This guide covers how to build the project, the repository conventions, and how changes are proposed and released. ## Feedback, questions & security All project contact happens through GitHub - there is no email support channel. - **Bugs, feature requests, questions, documentation issues** - open a [GitHub issue](https://github.com/kungfu-systems/buildchain/issues/new/choose). - **Code and documentation changes** - open a pull request. - **Security vulnerabilities** - report them privately, never in a public issue. See [`SECURITY.md`](SECURITY.md). Please do not include secrets, credentials, tokens, private logs, or other sensitive material in issues or pull requests. ## Prerequisites - Node.js 24 - Corepack with pnpm 11 - Go 1.25 or newer in major 1 for product verification Buildchain's reusable workflow consumers may build with npm, yarn, pnpm, CMake, Conan, Python, Docker, or other tools through lifecycle commands. This repository itself is a Node/pnpm workspace. ## Repository layout The [code organization contract](docs/code-organization.md) defines the layers. Consumer APIs and hosted job boundaries live in `.github/workflows`; semantic node adapters live in `actions///`; JavaScript business logic lives in `packages/core/`; authoritative Rust domains and the native host live in `crates`. `bin` contains the CLI entry, and `scripts` contains only repository tooling. Schemas, ownership declarations and tests live in `contracts`, `architecture` and `tests`. Preserve published consumer contracts when moving an implementation. Historical entry paths are explicitly retained in `architecture/consumer-upgrade.json` and generated from the current canonical workflow. Their input defaults, outputs, permissions and job contexts remain part of the upgrade contract. Do not add unregistered aliases or independently maintained copies. ## Build and verification ```sh corepack enable pnpm pnpm install --frozen-lockfile pnpm run check ``` `pnpm run check` performs the repository done-check: - validates inventory data; - lints all root workflows, including hidden reusable workflows; - runs unit tests with `node --test`; - rebuilds action bundles through each action package. For narrower checks during development: ```sh pnpm run test:unit pnpm run check:workflows pnpm run build npm pack --dry-run --json --registry=https://registry.npmjs.org/ ``` ## Workflow organization All workflows remain directly under `.github/workflows/`. The finite role and category vocabulary is enforced by `architecture/workflow-taxonomy.json`: | Role | Filename | Scope | | --- | --- | --- | | Public | `public-ops-pipeline.yml`, `public-ops-recover.yml` | Normal execution and exact-attempt recovery | | Component | `.-.yml` | Internal runtime topology or dispatch service | | Self | `buildchain.yml`, `buildchain-recover.yml` | Generated normal and recovery callers | Categories are only `build`, `release`, and `ops`. Register the identity, role, category, purpose, owner, lifecycle status, invocation, and rationale before adding its derived filename. The [Workflow Catalog](docs/workflow-catalog.md) lists every canonical API and component path. New consumers select the two public entries; actions and product-specific components are internal. Self automation has only the generated normal and recovery entries. Existing consumers retain the published paths registered in the consumer upgrade contract. The checker verifies their generated bodies against the canonical implementation; they add no repository event roots. A matching prefix alone does not admit an unregistered workflow. `validate`, `doctor`, and consumer source inspection check the generated caller bytes and the registered implementation inventory separately. A repository that also implements the runtime may retain its declared workflow libraries. Every library must pass the same taxonomy checks; an extra repository event root or unregistered workflow is rejected, including in Buildchain's own repository. Source inspection follows product commands, package scripts and reachable local modules, rejecting recognized publication or recovery control calls before a product runs. Unsupported syntax, dynamic code and external tools remain explicit unresolved diagnostics; passing the control checks is not proof of a complete static program graph. Product commands still run in the runtime's read-only jobs with filtered child environments and private command files. The required tests enforce this boundary for normal builds, publication builds and version generation. Independent provider qualification grants authority; a product's output cannot. This boundary does not claim to sandbox arbitrary hostile code on a local machine. Run `pnpm run generate:workflows`, `pnpm run check:workflows`, then the full `pnpm run check`. The product verification commands run this gate through the shared pipeline on PRs, merge queue candidates, and protected source qualification. Policy, enforcement, and ownership changes require independent `@kungfu-origin` review. A development merge does not publish a floating channel. Consumers adopt the new API only after that channel publishes it and their contract locks are refreshed. Qualify a new Alpha through the generated `@v4-alpha` caller pair and matching Alpha lock on an isolated qualification branch. Self checks accept either shared channel template as a complete pair, while initialization defaults to `@v4`. ## Generated files GitHub Actions consume committed bundles. When changing an action implementation, run the action build and commit the updated `dist/index.js` alongside the source files. ## Commit messages - Write commit messages and pull request descriptions in **English**. - Follow lightweight [Conventional Commits](https://www.conventionalcommits.org/) (`type(scope): summary`), for example `fix(publish): resume finalizing refs`. - Sign every commit with the Developer Certificate of Origin: ```sh git commit -s -m "docs: add public repository onboarding" ``` The sign-off adds a line like: ```text Signed-off-by: Your Name ``` Pull requests are checked automatically; every commit must include this line. ## Branches, pull requests & releases Development happens on channel branches per version line, promoted by pull request: ```text dev/vX/vX.Y -> alpha/vX/vX.Y -> release/vX/vX.Y release/vX/vX.Y -> publish-gate/major ``` - Open normal changes against the relevant `dev/*` branch. - Treat `dev/vX/vX.Y` branches as protected development channels. Do not use them for direct ad-hoc commits. Work from `feature/*`, `fix/*`, `chore/*`, `docs/*`, `ci/*`, or `refactor/*` branches and open a PR into the target dev line. - The generated `buildchain.yml` caller invokes `public-ops-pipeline.yml` using a published floating entry. Product build, verification, artifacts, channels and review policy are declared in the schema-2 TOML. - The published runtime owns source qualification, protected review and merge, version materialization, publication, provider readback and next-development. - Recover an interrupted operation through `buildchain-recover.yml` using its exact attempt and, when required, one transient repaired runtime. Recovery does not accept replacement source, artifact or provider-effect parameters. - Both generated callers use the published `@v4` entry and the default `.buildchain/buildchain.toml` policy path. Adopt the stable contract lock only after the published entry has qualified; see `AGENTS.md` for target-policy admission requirements. See [`docs/release-governance.md`](docs/release-governance.md), [`docs/release-flow.md`](docs/release-flow.md), and [`docs/runtime-train-validation.md`](docs/runtime-train-validation.md). ## License By contributing you agree that your contributions are licensed under the project's [Apache License 2.0](LICENSE). Buildchain uses the Developer Certificate of Origin (DCO) and does not require a Contributor License Agreement (CLA). ## Implementation names Name implementation directories, scripts, functions, and runtime work directories for their responsibility. Product generation prefixes such as `v4-` are rejected by `pnpm run check:implementation-naming`, including nested JavaScript bindings and Rust declarations. `architecture/implementation-naming.json` records the current implementation identities and prohibited generation prefixes. Published schema identities, hash domains, selectors, runner labels, API compatibility keys, and exact historical evidence keep their established identities; they do not name new implementations. Stable completion under `semver/auto` prepares the next patch at `alpha.0` from the exact current protected development commit. See the generated [next-development contract](docs/next-development-transition.md) for retry, independent review, and publication-preservation behavior. Stable eligibility is checked before publication. Once the native publication phase has succeeded, distribution and next-development continue from the retained publication, source and runtime. Later Alpha PR events do not restart that gate; the follow-up stages still verify their original publication and protected merge.