From 3bddabcdc9f6a6eb332a9bb49c7217ad46d7b334 Mon Sep 17 00:00:00 2001 From: Said Nizamutdinov Date: Fri, 17 Apr 2026 10:36:43 +0300 Subject: [PATCH] Add AGENTS.md with unified section order New contributor guide following the shared 7-section template: Project Layout, Build and Verification, Implementation Rules, Testing Expectations, Versioning and Docs, Commit Rules, Pull Requests, Security and Configuration. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dfed0a1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,81 @@ +# Repository Guidelines + +## Project Layout + +- `src/main.rs`: entrypoint — parses CLI and delegates to `run()`. +- `src/cli.rs`: Clap definitions and help text. +- `src/auth.rs`: credential resolution from env vars, embedded config, or interactive prompt. +- `src/client.rs`: YouTrack SDK client setup. +- `src/commands/`: user-facing handlers for `issue`, `comment`, and `attachment`. +- `src/output.rs`: shared table and JSON output helpers. +- `src/error.rs`: error types and exit-code mapping. +- `.github/workflows/ci.yml`: GitHub Actions workflow for tests and release artifacts. +- `CHANGELOG.md`: user-visible change log. + +## Build and Verification + +- `cargo fmt --all`: format the workspace. +- `cargo check`: validate the crate. +- `cargo test`: run unit tests. +- `cargo clippy --all-targets -- -D warnings`: lint this crate. +- `cargo run -- --help`: smoke-test the CLI locally. +- `make build`: build the host binary. +- `make build-locked YOUTRACK_URL=... YOUTRACK_TOKEN=...`: build the locked host binary. +- `make install-binary`: install the host build from `target/release/youtrack-cli`. +- `make ci`: runs fmt-check + lint + test. +- GitHub Actions uploads release artifacts for `macos-silicon`, `linux-x64`, and `linux-x86`. + +## Implementation Rules + +- Follow `rustfmt` defaults: 4-space indentation, no manual alignment, trailing commas where formatter-friendly. +- Use `snake_case` for modules and functions. +- Use `PascalCase` for types and enums. +- Keep command DTOs explicit and serializable. +- Keep `src/main.rs` and the Clap layer thin. +- Keep direct YouTrack API logic in `src/client.rs` or via the SDK, not in CLI structs. +- Prefer small facade methods and thin command handlers over cross-layer abstractions. + +## Testing Expectations + +- Add tests beside the code they cover. +- Keep CLI parser coverage in `src/cli.rs` under `#[cfg(test)]`. +- Follow the existing `parses_*` and `rejects_*` naming pattern. +- New commands should include at least one happy-path parse test and one invalid-input test for conflicting flags. + +## Versioning and Docs + +- Behavior changes require a patch version bump in the root `Cargo.toml`. +- Keep the version bump in the same commit as the behavior change. +- Update `CHANGELOG.md` after every commit and add the newest entry first under the current branch section. +- Update `AGENTS.md` only when architecture, conventions, dependencies, versioning rules, or repo workflows change. + +Behavior changes include changes in `src/`, config resolution, request building, auth, output shaping, error mapping, or contributor workflows that change how the project is built, tested, released, or consumed. + +## Commit Rules + +- Keep commits small and imperative. +- Capitalize the first word and omit the trailing period. +- Keep the subject at 72 characters or fewer. +- Do not use conventional-commit prefixes. +- Focus the subject on what changed and why it matters. + +Examples: +- `Add issue comment commands` +- `Add attachment upload support` + +After each commit: +1. Update `CHANGELOG.md`. +2. Update `AGENTS.md` if repo conventions changed. +3. Amend the commit so those documentation updates stay in the same commit. + +## Pull Requests + +- Include a short user-visible summary. +- List verification performed, such as `cargo test` or `cargo clippy --quiet --no-deps`. +- Call out config, credential, or embedded-build impact. + +## Security and Configuration + +- Do not hardcode runtime secrets in source. +- Treat embedded-token builds as secret-bearing artifacts. +- Credentials resolve in order: env var > embedded config > interactive prompt.