# Alexion's Monorepo

## Commit convention

- Use Conventional Commits for all commit messages.
  Before writing a commit message, read `docs/conventional-commits.md`.
- Keep commit messages about the Git history, not the forge workflow.
  Include external references only when they are stable context for the change.
- Do not add agent attribution or co-author trailers.

## Technical writing

- Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose.
  Use the nearest project dictionary for project-specific domain language.

## Pull requests

- During pull-request development, add follow-up commits instead of amending existing commits.
  Preserve review history until the pull request is ready to merge.

## Forge workflow

- Use `gitea-axi` for Gitea issues, pull requests, labels, reviews, comments, and milestones.
  It resolves this repository from the `origin` remote inside the checkout.

## Tooling

- When a command is missing from the ordinary environment, prefer running it through Nix instead of installing it ad hoc.
  For example, use `nix shell nixpkgs#python3 -c python3 <script>` for one-off Python commands.
- Stage new files that Nix discovers through flake evaluation before testing.
  Flake evaluation ignores untracked files, so auto-loaded modules must be tracked before `nixos-rebuild --flake` can see them.

## Gotchas

- When materializing an external specification, standard, or project-maintained convention, use the upstream source instead of reconstructing it from memory.
  Preserve local policy separately from copied upstream text.
- After an explicit squash or rewrite request on a pull request, subsequent pull-request updates still use follow-up commits unless the user explicitly asks for another rewrite.
- Starlark top-level rule and extension declarations cannot reference implementation functions before those functions are assigned.
  Keep executable public interface declarations after their implementation symbols, or validate before committing a top-down rewrite.
- `rules_rust` `rust_test` targets cannot set both `crate` and `srcs`.
  Use one input style per test target.