vhaudiquet
84405a6762
The library holds only the state its own types need when a Ctrl+C arrives: the interrupted flag flows check to stand down, the cleanup hook registry for resources that must not outlive the process (the ephemeral build chroot), and the live view's reporter slot. The signal handling itself is CLI wiring and lands separately: nothing here installs handlers, prints or exits, so a library consumer embedding these types keeps its own signal disposition.
108 lines
4.6 KiB
Markdown
108 lines
4.6 KiB
Markdown
# 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/`)
|
|
- `interrupt` — Ctrl+C interception and interrupt-time cleanup
|
|
(`src/interrupt.rs`)
|
|
- `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. |