# AGENTS.md

Conventions for working in this tree. They apply to every commit; the
whole history follows them.

## Before every commit

Run, in order, and make sure they are clean before committing:

```sh
cargo fmt --all
cargo clippy --all-targets --all-features   # zero warnings
```

CI builds and lints with `RUSTFLAGS: -Dwarnings`, so a `cargo build`
warning fails the gate too. `cargo fmt` may amend files you did not
touch — include those changes in the commit (or in a separate `fmt:`
commit) rather than leaving the tree dirty.

The test suite is heavy (chroots, ssh, network): always run the
`#[cfg(test)]` modules of what you touch, and the full suite when
changing shared plumbing (`report`, `logfmt`, `test_support`,
`debian/`). Tests marked `#[ignore]` shell out or hit the network and
are for deliberate ad-hoc runs (`cargo test -- --ignored`), not for the
pre-commit pass. Building needs the gpgme/openssl system packages
(`pkg-config libssl-dev libgpg-error-dev libgpgme-dev`).

## Commit messages

There are no conventional-commit types; the format is a component scope
and a summary:

```
<scope>: <short summary>
```

Rules:

- The scope is the component touched — the module under `src/` (file or
  directory), named after the user-facing subcommand when that differs:
  - `pull` — source package download (`src/pull.rs`)
  - `chlog` — changelog entry generation (`src/changelog.rs`)
  - `build` — source package builds, .dsc (`src/build/`)
  - `deb` — binary package builds, .deb (`src/deb/`)
  - `put` — PPA/archive upload (`src/put/`)
  - `new` — package scaffolding (`src/new/`)
  - `lint` — tree linting (`src/lint/`)
  - `prune`, `package_info` — remaining subcommand modules
  - `context` — build contexts: local, ssh, chroot/schroot, unshare
    (`src/context/`)
  - `debian` — Debian format primitives: control, versions, checksums,
    arch (`src/debian/`)
  - `apt`, `launchpad`, `distro_info`, `quirks` — archive/distro
    integration
  - `report` — BuildView/Prompter ports and the views implementing them
  - `ui`, `logfmt` — terminal rendering and output classification
  - `data` — the `data/*.yml` embed convention itself; content changes
    to a data file belong to the commit of the module consuming it
  - `cli` — the binary, argument wiring (`src/main.rs`)
  - `test` — test-only changes (shared plumbing: `src/test_support.rs`)
  - `deps` — dependency additions/bumps (manifests, lockfile)
  - `fmt`, `clippy` — rustfmt/clippy fixups
  - `ci`, `snap`, `docs` — workflows, snap packaging, README
- Use the submodule path when the change is confined to one
  (`apt/keyring`, `debian/version`).
- A commit touching several components should be split into one commit
  per component when practical; otherwise comma-join the scopes without
  spaces (`pull,deb`).
- Summary: imperative mood, lowercase first letter (proper nouns keep
  theirs: Ubuntu, SRU, lintian), no trailing period, max ~72 characters.
- Body (expected for anything nontrivial): separated by a blank line,
  wrapped at 72 columns; explain why, and the design when the approach
  was a choice among alternatives. Reference issues as `#123`.
- Reverts use git's default `Revert "<original subject>"`.

### Examples

```
chlog: fall back to the changelog history when no version tag exists
ui: ellipsize fake-terminal pane lines wider than the terminal
lint: add pkh lint, wrapping lintian for parity plus pkh-native checks
chlog: number Ubuntu backports with the per-release SRU scheme
deb: resolve cross pkg-config against the target multiarch
pull,deb: add top-level --pocket option
debian/version: dpkg-compatible version comparison
deps: bump git2 to 0.21
fmt: apply rustfmt
docs: refresh the README roadmap for 1.0
```

## Code

- The crate denies missing docs (`#![deny(missing_docs)]` in
  `src/lib.rs`): every public item carries a doc comment, and the module
  list there is the layout map — keep it in sync when adding a module.
- Subcommand business logic lives in the library and reports through the
  `report` ports (`BuildView`, `Prompter`) instead of printing;
  `src/main.rs` is argument wiring only. Subprocess output
  classification is pure logic in `logfmt`, testable without a pty.
- Static reference data (series tables, keyserver URLs, licenses,
  forges, templates) lives in `data/*.yml`, embedded with the
  `embed_data!` macro — not in hardcoded tables.
- Comments state constraints the code cannot show; no narration.
- Anything user-facing (subcommands, flags, option defaults) is
  reflected in `README.md` — including its roadmap checklists — before
  commit.