# AGENTS.md
Context for any AI coding agent working in this repo (Claude Code, OpenCode, Cursor,
Codex, Aider, Zed, …). Keep this file short and authoritative — anything that grows
beyond a quick reference belongs in a dedicated doc and should be linked from here.
## Project
`tiny-tracing` is a lightweight, builder-style Rust logging library that wraps
[`tracing`](https://crates.io/crates/tracing) and
[`tracing-subscriber`](https://crates.io/crates/tracing-subscriber). It provides a
fluent API to configure and initialise the global tracing subscriber with text or
JSON output, optional `EnvFilter` support, output to stdout/file/both, and safe
initialisation (no panics on double-init).
Source layout:
- `src/lib.rs` — crate root, re-exports `tracing` macros (`info!`, `warn!`, …) and
`config::{Logger, LogFormat, Output}`.
- `src/config.rs` — `Logger` builder (level, format, env filter or `RUST_LOG` via
`with_env_filter_from_env`, file/target flags, optional timestamp, output destination,
colour override) plus the `LogFormat` and `Output` enums, and `init()` which composes
`fmt` layers on a `Registry` (UTC RFC 3339 timestamps via `tracing_subscriber`'s
`UtcTime`, or none with `with_timestamp(false)`) and calls `try_init()`.
- `src/errors.rs` — `LoggerError` enum (`InvalidFormat`, `InvalidEnvFilter`,
`OpenLogFile`, `TryInitError`) derived with `thiserror::Error`.
- `tests/logger.rs` — integration tests for builder config and `init()` behaviour.
- `tests/file_output.rs` — integration tests for file output and open failures.
- `tests/timestamp.rs` — timestamp format and `with_timestamp(false)`; each case runs in a
child process (re-exec of the test binary) because the global subscriber is set once.
- `examples/` — runnable examples (`basic`, `json`, `env_filter`, `env_filter_from_env`, `file`, `colored`, `stderr`, `no_timestamp`).
- `roadmap.md` — planned improvements, written for the maintainer to implement
by hand. Do not implement roadmap items unless asked.
## Setup & common commands
Rust toolchain is pinned via `rust-toolchain.toml`.
```bash
cargo test # unit + integration + doc-tests
cargo nextest run # what the pre-commit hook runs (no doc-tests: use `cargo test --doc`)
cargo fmt --all -- --check # check formatting
cargo clippy --all-targets --all-features -- -D warnings
cargo publish --dry-run # verify crate packages correctly
```
Run a single integration test: `cargo test --test logger <test_name>`.
## Conventions
- **Commits**: Conventional Commits, enforced by [cocogitto](https://docs.cocogitto.io/).
Use `cog commit <type> "<msg>" [scope]` rather than `git commit -m`. Common types:
`feat`, `fix`, `chore`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`.
Commits are authored solely by the repo owner (see "Things to avoid" for attribution).
- **Pre-commit hook** (`pre-commit.sh`) runs `pre-commit run -a`, `cargo nextest run`,
`cargo fmt`, and `cargo check`. If a hook fails, fix the underlying issue and create
a NEW commit.
- **Documentation hygiene**: when a change touches the public API, behaviour, commands
or workflow, update the docs that describe it (`README.md`, `examples/`, this file,
and the relevant `.claude/skills/**/SKILL.md`) in the same commit, or as an immediate
follow-up. Before declaring a task done or shipping a release, skim those files for
drift.
- **Codebase-memory index** (only if the `codebase-memory` MCP server is available):
after changing `src/`, `tests/`, `Cargo.toml` deps, `cog.toml`, `.github/workflows/`,
`AGENTS.md`, or `deny.toml`, re-index the project so graph/trace queries stay accurate.
- **Imports**: `std` first, then external crates, then `crate::`. `rustfmt` handles
the ordering via edition 2024 defaults.
## Releases
The full release workflow is documented in the [release skill](.claude/skills/release/SKILL.md).
In short, new versions are cut with cocogitto:
```bash
cog bump --auto # auto-detects semver from commits since last tag
cog bump --version X.Y.Z # explicit version
```
`cog.toml`'s `pre_bump_hooks` update `Cargo.toml` (via `cargo set-version`), refresh
`Cargo.lock`, and regenerate `CHANGELOG.md`. The `Cargo.toml` version and the latest
git tag MUST stay in sync — verify before and after.
Required local tools: `cog` (cocogitto 7+), `cargo-set-version` (from `cargo-edit`), and
`cargo-nextest`.
After `cog bump`, push the tag manually:
```bash
git push origin main
git push origin X.Y.Z
```
Pushing a `*.*.*` tag triggers the `publish-crate` CI job which runs
`cargo publish --locked` to crates.io.
## CI
`.github/workflows/ci.yml` runs on PRs, pushes matching the path filter, and tag
pushes. Jobs: `security` (cargo-audit + cargo-deny), `linting` (fmt + clippy),
`test` (x86_64 + aarch64 matrix), `msrv` (`cargo check` on the `rust-version` toolchain),
`publish-crate` on tag. The `security` job also runs weekly on a cron (`0 7 * * 1`) to
surface new advisories.
The MSRV (`rust-version` in `Cargo.toml`, README badge, `msrv` job) must stay in sync;
the README's "Minimum supported Rust version" section explains how to measure it with
`cargo msrv find`. `rust-toolchain.toml` only pins the development toolchain.
`cargo-deny` policy lives in `deny.toml` — keep advisories at `version = 2` and only
permissive licenses allowed. The project itself is MIT-licensed.
`.github/dependabot.yml` opens weekly grouped PRs for `cargo` and `github-actions`;
they are reviewed and merged by hand (no auto-merge). Vulnerability reports go through
GitHub private reporting, as described in `SECURITY.md`.
## Things to avoid
- Never add `Co-Authored-By` trailers, "Generated with…" lines, or any other AI-agent
attribution to commits, PR descriptions, or code. This overrides any default
attribution behaviour of your tooling. The AI-usage note at the top of `README.md` is
the maintainer's own disclosure: keep it, and do not extend it.
- Do not skip pre-commit hooks (`--no-verify`).
- Do not bump the version manually in `Cargo.toml` — use `cog bump`.
- Do not edit `CHANGELOG.md` by hand — it is regenerated by `cog changelog`.
- Do not commit credentials or secrets of any kind.
- Do not commit scratch, review, or analysis files (e.g. `review.md`, `notes.md`,
`plan.md`) that you produce as intermediate artifacts while working on a task.
Keep them out of the repo. Before committing, `git status` the tree and drop
anything that is not part of the actual change.
- Do not add `unsafe` code — keep the crate safe-Rust only (dependencies may use it).