docs: clarify repo agent guidance
This commit is contained in:
Ogulcan Celik
parent
f928f33a01
commit
a1ba035707
106
AGENTS.md
106
AGENTS.md
|
|
@ -37,79 +37,91 @@ After the change is integrated, remove the task worktree and delete the task bra
|
|||
|
||||
## Testing
|
||||
|
||||
Use `just` recipes by default for tests and checks instead of invoking cargo or scripts directly.
|
||||
Use `just` recipes by default instead of invoking cargo or scripts directly.
|
||||
|
||||
```bash
|
||||
just test # cargo nextest + maintenance script tests
|
||||
just check # formatting check + cargo nextest + maintenance script tests
|
||||
```
|
||||
|
||||
Default flow: run `just check` before committing. Do not commit until `just check` passes locally unless Can explicitly accepts a narrower validation for that commit.
|
||||
Run `just check` before committing unless Can explicitly accepts narrower validation. Do not bypass failing checks; fix the failure or explain exactly why a narrower check is enough.
|
||||
|
||||
Unit tests live next to the code (`#[cfg(test)] mod tests`). If you add behavior to `AppState` or `Workspace`, it should be testable with `AppState::test_new()` and `Workspace::test_new()` — no PTYs.
|
||||
Unit tests live next to the code (`#[cfg(test)] mod tests`). New `AppState` or `Workspace` behavior should be testable with `AppState::test_new()` and `Workspace::test_new()` without PTYs.
|
||||
|
||||
## Conventions
|
||||
## Docs
|
||||
|
||||
- Conventional commits, lowercase, no emojis.
|
||||
- Do not edit root `README.md` or `CHANGELOG.md` during normal feature or fix work unless explicitly asked. Maintainers prepare `docs/next/README.md` and `docs/next/CHANGELOG.md` during release review.
|
||||
- Treat website docs under `website/src/content/docs/` as the latest released public docs. These are Astro Starlight MDX docs published on herdr.dev. Do not document unreleased behavior there during normal feature or fix work.
|
||||
- Treat `docs/next/README.md` and `docs/next/CHANGELOG.md` as next-release staging for the root README and changelog. Treat `docs/next/website/src/content/docs/` as a full next-release mirror of `website/src/content/docs/`; these staged MDX files are the source for the next herdr.dev docs.
|
||||
- During normal work, update `docs/next/website/src/content/docs/` for unreleased website doc changes, not `website/src/content/docs/`. Before release, copy the approved mirror back to `website/src/content/docs/`. `just release-docs-check` verifies README/changelog sync, the website docs mirror is 1:1 with released website docs, and the removed root docs stay removed.
|
||||
- Put local PRDs, planning notes, and exploratory specs under `.local/prd/`; `.local/` is ignored and locally controlled.
|
||||
- Integration asset versions (`HERDR_INTEGRATION_VERSION` markers and matching `*_INTEGRATION_VERSION` constants) are migration versions relative to the latest released tag, not per-commit counters on `master`. If an integration asset changes multiple times between releases, bump it once from the version in the latest release. Before changing one, compare against the latest release tag and keep the asset marker and Rust expected constant aligned.
|
||||
- When a normal feature or fix commit relates to a GitHub issue, add a commit body line `refs #<issue-number>` after the subject. Use this shape:
|
||||
```text
|
||||
fix: handle pane focus
|
||||
Stable public docs live in `website/src/content/docs/`. They are the currently released herdr.dev docs. Do not document unreleased behavior there during normal feature or fix work.
|
||||
|
||||
refs #82
|
||||
```
|
||||
Do not use GitHub closing keywords like `fixes #<issue-number>`, `closes #<issue-number>`, or `resolves #<issue-number>` in normal commits, because `master` contains unreleased work and those keywords close issues before release. Release CI scans `refs #<issue-number>` body lines between release tags and closes the referenced issues after the GitHub Release is created.
|
||||
- Rust: no `unwrap()` in production code. `tracing` for logging. `#[allow]` only with a comment explaining why.
|
||||
- Don't bypass checks. If tests fail, fix them before committing.
|
||||
- Don't add dependencies without a reason. Check if the existing deps cover it first.
|
||||
Unreleased docs live in `docs/next/website/src/content/docs/`. Update those when a user-facing change needs docs before the next release. `docs/next/README.md` and `docs/next/CHANGELOG.md` stage root README and changelog changes.
|
||||
|
||||
## Releases
|
||||
The website build runs `website/scripts/prepare-docs.mjs`. It keeps stable docs at `/docs/` and generates preview docs at `/docs/preview/` from `docs/next/website/src/content/docs/`. Do not edit generated `website/src/content/docs/preview/`.
|
||||
|
||||
Before cutting a release, run `/pre-release-audit` to compare commits since the last tag against `docs/next/CHANGELOG.md` and `docs/next/`, then copy approved next-release docs into `README.md`, `CHANGELOG.md`, and the matching website docs. The release script promotes the root changelog's `## Unreleased` section into the versioned entry and copies the prepared changelog back to `docs/next/CHANGELOG.md` so the next cycle starts clean.
|
||||
During release review, copy approved next docs into the stable docs and run `just release-docs-check`. Normal feature/fix work should not edit root `README.md`, root `CHANGELOG.md`, or `website/latest.json` unless explicitly requested.
|
||||
|
||||
Default release flow:
|
||||
Put local PRDs, planning notes, and exploratory specs under `.local/prd/`; `.local/` is ignored and locally controlled.
|
||||
|
||||
## Commit Style
|
||||
|
||||
Use lowercase conventional commits, no emojis, and no AI co-author lines. Commit subjects feed preview release notes, so keep them descriptive.
|
||||
|
||||
Before committing, propose the commit message and get alignment.
|
||||
|
||||
When a normal feature or fix commit relates to a GitHub issue, add a commit body line `refs #<issue-number>` after the subject:
|
||||
|
||||
```text
|
||||
fix: handle pane focus
|
||||
|
||||
refs #82
|
||||
```
|
||||
|
||||
Do not use GitHub closing keywords like `fixes #<issue-number>`, `closes #<issue-number>`, or `resolves #<issue-number>` in normal commits. `master` contains unreleased work; release CI closes referenced issues after the GitHub Release is created.
|
||||
|
||||
## Code Conventions
|
||||
|
||||
- Rust: no `unwrap()` in production code. Use `tracing` for logging. Use `#[allow]` only with a comment explaining why.
|
||||
- Don't add dependencies without a reason. Check whether existing dependencies cover the need first.
|
||||
- Integration asset versions (`HERDR_INTEGRATION_VERSION` markers and matching `*_INTEGRATION_VERSION` constants) are migration versions relative to the latest released tag, not per-commit counters on `master`. If an integration asset changes multiple times between releases, bump it once from the version in the latest release.
|
||||
- When changing the server/client wire protocol, compare `src/protocol/wire.rs::PROTOCOL_VERSION` against the latest released tag. Bump it only if the current source protocol is not already greater than the latest released protocol. Update hardcoded protocol expectations and manual protocol fixtures in tests.
|
||||
|
||||
## Release Channels
|
||||
|
||||
Herdr has one main branch and two update channels. Stable and preview both build from `master`; there is no long-lived preview branch.
|
||||
|
||||
Normal users default to stable. Stable docs are `/docs/`, stable updates use `website/latest.json`, and Homebrew/Nix stay stable-only.
|
||||
|
||||
Preview is opt-in for direct Herdr installs:
|
||||
|
||||
```bash
|
||||
herdr channel set preview
|
||||
herdr update
|
||||
```
|
||||
|
||||
Switch back with:
|
||||
|
||||
```bash
|
||||
herdr channel set stable
|
||||
herdr update
|
||||
```
|
||||
|
||||
Preview releases are GitHub prereleases produced by `.github/workflows/preview.yml` on manual dispatch and the Wednesday/Friday schedule. The workflow updates `website/preview.json`, which the website build publishes as `/preview.json`. Do not hand-edit `website/preview.json`; fix the workflow or `scripts/preview.py` and rerun Preview.
|
||||
|
||||
Stable releases use:
|
||||
|
||||
```bash
|
||||
just check
|
||||
just release 0.x.y
|
||||
```
|
||||
|
||||
`just release 0.x.y` prepares the changelog entry, bumps `Cargo.toml`, updates `Cargo.lock`, runs tests, commits the release, pushes `master`, tags, and pushes the tag. GitHub Actions builds the binaries after the tag is pushed, creates the GitHub release, uploads all four binary assets, then updates `website/latest.json` on `master` automatically.
|
||||
Before stable release, run `/pre-release-audit`, finalize `docs/next`, copy approved docs into the stable docs/root files, and let `just release-docs-check` verify the sync. `just release` prepares the release commit, tags it, pushes the tag, and GitHub Actions builds binaries, creates the GitHub release, closes released issues, and updates `website/latest.json`.
|
||||
|
||||
`nix/package.nix` imports `Cargo.lock` directly with `cargoLock.lockFile`, so release version bumps do not require a separate Nix cargo hash update. If Cargo git dependencies are added later, add the required `cargoLock.outputHashes` entries as part of that dependency change.
|
||||
|
||||
The release workflow must publish these four assets:
|
||||
The release workflows must publish these four assets:
|
||||
|
||||
- `herdr-linux-x86_64`
|
||||
- `herdr-linux-aarch64`
|
||||
- `herdr-macos-x86_64`
|
||||
- `herdr-macos-aarch64`
|
||||
|
||||
`website/latest.json` is the shipped updater source of truth. Keep its schema aligned with `src/update.rs`:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.x.y",
|
||||
"notes": "### ...",
|
||||
"assets": {
|
||||
"linux-x86_64": "...",
|
||||
"linux-aarch64": "...",
|
||||
"macos-x86_64": "...",
|
||||
"macos-aarch64": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The app update check and the in-app **What's New** flow both depend on that exact manifest shape.
|
||||
|
||||
Do not edit `website/latest.json` during normal feature, fix, or test work. It describes the latest published release binaries, not the current unreleased source tree. The release workflow updates it after release assets are published.
|
||||
|
||||
When changing the server/client wire protocol, compare `src/protocol/wire.rs::PROTOCOL_VERSION` against the latest released tag. Bump it only if the current source protocol is not already greater than the latest released protocol. Multiple unreleased wire changes in the same release cycle must share the same single protocol bump; Herdr supports tagged releases, not arbitrary `master` client/server compatibility. When a bump is required, update all hardcoded protocol expectations and manual protocol fixtures in tests. Keep protocol test expectations intentionally explicit so compatibility changes are reviewed instead of silently following the constant.
|
||||
`nix/package.nix` imports `Cargo.lock` directly with `cargoLock.lockFile`, so release version bumps do not require a separate Nix cargo hash update. If Cargo git dependencies are added later, add the required `cargoLock.outputHashes` entries as part of that dependency change.
|
||||
|
||||
## External contributor guardrail
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue