commit type

docs commit template

A commit that changes documentation only: README files, API docs, inline comments, or guides — no production code changes.

format

docs(scope): short imperative description of what was documented

- what was added or updated (bullet 1)
- what was removed or corrected (bullet 2)

Why the documentation change was needed: outdated info, missing coverage,
or new feature that required documentation. Max 72 chars/line.

real examples

docs(api): add OpenAPI 3.1 schema for /payments endpoints

- document all query parameters, request bodies, and response schemas
- add example payloads for 200, 400, 401, 422, and 500 responses
- add authentication section referencing Bearer token format

The payments API was undocumented; client teams were reverse-engineering
the schema from network logs rather than a canonical specification.

docs(readme): update installation section for Homebrew tap

- replace manual binary download instructions with brew install command
- add brew tap gitagenthq/tap prerequisite step
- remove outdated go install fallback that no longer works with v2 module path

The README still showed the pre-release installation method; new users
were filing issues because the old instructions failed on Apple Silicon.

docs(contributing): add commit message format guide with examples

- document the type(scope): subject format requirement
- add a table of valid types with descriptions and version bump impact
- add five example commits covering feat, fix, refactor, docs, and chore

Contributors were submitting PRs with unformatted commit messages; the
guide gives them a reference before they open a PR rather than after
review feedback.

docs(architecture): add sequence diagram for the OAuth2 PKCE flow

- add Mermaid sequence diagram showing client, auth server, and resource server
- document the code verifier and code challenge generation steps
- link to RFC 7636 for the full PKCE specification

The onboarding doc referred to the PKCE flow without explaining it; new
engineers spent hours in the RFC when a diagram would have sufficed.

when to use

Use docs for any change that is purely textual and affects only documentation: README, CONTRIBUTING, inline code comments, JSDoc/godoc/rustdoc annotations, wiki content, or docsite pages.

git-agent automatically analyzes your changes and infers the correct commit type.

brew install gitagenthq/tap/git-agent

FAQ

Should I use docs for JSDoc or inline comment changes?

Yes, if the comments are the only change. If inline comments accompany a code change, include them in the same commit with the appropriate type (feat, fix, refactor).

Does docs appear in generated changelogs?

Not by default. Standard changelog presets exclude docs from the public changelog. You can configure your changelog tool to include it if your project has public API documentation that users should track.

Should Storybook stories use docs or test as the commit type?

Either is reasonable depending on your team convention. docs is appropriate when stories serve as living documentation. test is appropriate when stories are used as visual regression test baselines.

What are Conventional Commits?Commit message format Conventional changelog