docs(main): add AGENTS.md guidelines #738
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,41 @@ | ||||||
| # Repository Guidelines | ||||||
|
|
||||||
| ## Project Structure & Module Organization | ||||||
|
|
||||||
| - `main.go`: CLI entrypoint. | ||||||
| - `cmd/`: Cobra command tree (grouped by domain: `auth/`, `policy/`, `tdf/`, etc.). | ||||||
| - `pkg/`: Core implementation used by commands (notably `pkg/handlers/`, `pkg/profiles/`, `pkg/auth/`, `pkg/utils/`). | ||||||
| - `docs/man/`: User-facing command docs consumed by the CLI (see `pkg/man`). | ||||||
| - `e2e/`: End-to-end tests written in BATS (`*.bats`) plus helper scripts. | ||||||
| - `tui/`: Experimental interactive UI; treat as unstable unless you’re explicitly working on it. | ||||||
| - `adr/`: Architecture decision records. | ||||||
|
|
||||||
| ## Build, Test, and Development Commands | ||||||
|
|
||||||
| This repo is Go-first (module: `github.com/opentdf/otdfctl`) and pins a toolchain in `go.mod` (`go1.24.11`). | ||||||
|
|
||||||
| - `make run`: Run locally via `go run .`. | ||||||
| - `make test`: Run unit tests (`go test -v ./...`). | ||||||
| - `go test ./... -short -race -cover`: Matches CI’s unit test flags. | ||||||
| - `make build`: Cross-compile release artifacts into `target/` and `output/` (also runs tests and checksum steps). | ||||||
| - `make build-test`: Build a test-mode binary (`otdfctl_testbuild`) for local workflows. | ||||||
| - `make test-bats`: Run e2e BATS suite (requires `bats` installed and a running OpenTDF platform). | ||||||
|
|
||||||
| ## Coding Style & Naming Conventions | ||||||
|
|
||||||
| - Go formatting is enforced: run `gofmt` (and prefer `goimports` for imports) before pushing. | ||||||
| - Package names: lowercase; exported identifiers: `PascalCase`; errors: `ErrX` where appropriate. | ||||||
| - Keep command wiring in `cmd/**` and business logic in `pkg/**` (especially `pkg/handlers/**`). | ||||||
| - If you add/modify commands or flags, update the matching docs in `docs/man/`. | ||||||
|
|
||||||
| ## Testing Guidelines | ||||||
|
|
||||||
| - Unit tests live alongside code as `*_test.go`; keep table tests readable and deterministic. | ||||||
| - E2E tests are `e2e/*.bats`; be mindful of terminal sizing (`e2e/resize_terminal.sh`). | ||||||
|
|
||||||
| ## Commit & Pull Request Guidelines | ||||||
|
|
||||||
| - Follow Conventional Commits as seen in history (e.g., `feat(core): …`, `fix(ci): …`, `chore(dependabot): …`; use `!` for breaking changes). | ||||||
| - DCO sign-off is required: `git commit -s -m "feat(core): …"`. | ||||||
| - PR titles are linted for semantic format: types `fix|feat|chore|docs` and scopes `main|core|tui|demo|ci|dependabot`. | ||||||
|
Contributor
There was a problem hiding this comment. The guidance on commit messages could be slightly confusing. Line 38 refers to 'Conventional Commits', which has a broad set of standard types, but this line restricts them to a smaller list for PR titles. To avoid ambiguity, I suggest clarifying that PR titles are linted against a specific subset of Conventional Commit types.
Suggested change
|
||||||
| - PRs should include a short description, linked issue (if any), and note any user-visible CLI output changes. | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hardcoding the Go toolchain version here makes the documentation brittle, as it can become outdated when
go.modis updated. To improve maintainability, I recommend removing the specific version and instead directing the reader to thego.modfile. I've also added backticks for consistency with the rest of the document.