This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Contributing

Develop, test, and document changes locally.

Issues and pull requests are welcome. Keep changes narrow, preserve the security boundaries, and include evidence proportional to the risk.

Development setup

The aibox workspace installs the pinned Rust toolchain and cargo-audit. The production implementation is entirely Rust. Python and uv are development-only dependencies for repository policy, OpenTofu, and Ansible tests; they are not part of the installed product.

uv sync --all-groups
scripts/bootstrap-security-tools
scripts/validate-all
scripts/test-all

Python, Rust, and Markdown lines are hard-wrapped at 80 columns. Use Conventional Commits and never bypass hooks.

Branches

main contains the latest published stable release. Normal implementation work integrates through v0.x-dev; feature branches start from and merge back to that branch.

See the branching strategy for the maintenance, development, prerelease, and stable-release promotion lanes.

Documentation

Build the site before opening a documentation change:

docs/scripts/build-docs.sh

Write task-oriented procedures as guides, stable facts as reference, and design rationale in concepts. Update the README only as the concise front door; the documentation site remains the detailed source.

Infrastructure changes

Infrastructure changes should include:

  • strict contract or policy coverage;
  • positive and negative tests;
  • exact dependency pins;
  • direct-tool equivalents;
  • redacted evidence;
  • a teardown plan before any live apply.

Live cost-bearing tests require separate explicit approval.

1 - Branching strategy

Promote v0 changes through isolated development and release lanes.

ainfra uses separate long-lived lanes for stable maintenance and v0 development.

Long-lived branches

  • main represents the latest published stable release. Stable release tags are merged here after publication. It is the repository’s default branch.
  • v0.x-maintenance carries supported fixes for published v0 releases. Features are not backported unless explicitly approved.
  • v0.x-dev is the normal integration branch for v0 implementation. Feature branches and pull requests target this branch.
  • v0.x-pre-release receives selected promotions from v0.x-dev for alpha, beta, and release-candidate validation. Prerelease tags are created only here.
  • v0.x-release is promoted from the accepted prerelease state for general availability. Stable v0 tags are created here and then merged into main.

Promotion flow

feature branch
    → v0.x-dev
    → v0.x-pre-release
    → v0.x-release
    → main

Maintenance fixes begin on v0.x-maintenance. Promote a maintenance release through the same validation expectations, and merge any still-relevant fix forward into v0.x-dev.

Rules

  • Never tag releases from v0.x-dev.
  • Promote tested commits forward through pull requests; do not develop directly on release-integration branches.
  • Keep supported maintenance work isolated from new development.
  • Use squash-merged pull requests with green local validation.
  • Build and verify release artifacts locally before tagging.
  • Treat published tags as immutable.
  • Keep deployment-only branches, such as gh-pages, outside the source promotion flow.

Release verification

Run the complete local gate before entering the release lane:

./scripts/maintain.sh test

The container-side release builds and verifies both Linux targets before publishing them:

AINFRA_RELEASE_CONFIRM=v0.1.0 \
  ./scripts/maintain.sh release 0.1.0

On macOS, the host phase builds both Darwin targets, verifies all four local archives and checksum sidecars, uploads the Darwin assets, and then confirms that the GitHub release contains every expected archive, checksum, and the installer:

AINFRA_RELEASE_CONFIRM=v0.1.0 \
  ./scripts/maintain.sh release-host 0.1.0

To recheck a collected four-target artifact set without publishing anything:

./scripts/maintain.sh audit-release 0.1.0

Versioned documentation

The documentation root always represents main, the latest published stable state. The Releases menu links to immutable documentation snapshots for published versions.

Publish the current stable documentation:

docs/scripts/deploy-docs.sh

When publishing a release, first add its version and URL to params.versions in docs/hugo.yaml. Build the accepted release commit or tag and publish its snapshot under the matching path:

DOCS_VERSION=v0.1 docs/scripts/deploy-docs.sh

That command preserves the root site and replaces only /v0.1/. Versioned pages identify themselves as archived snapshots and link readers back to the latest documentation. Once published, a versioned snapshot should be treated as immutable except for an explicitly approved documentation correction.