Documentation Commit (docs type)
How to write a docs commit message for documentation-only changes. Understand when to use the docs type in Conventional Commits.
Detailed Explanation
The docs Type
The docs type is used when a commit only changes documentation. This includes README files, API documentation, inline code comments, guides, and configuration file comments. It does not trigger a version bump in standard semantic-release configurations because documentation changes do not affect the runtime behavior of the software.
Examples
docs: update API authentication guide
docs(readme): add installation instructions for Windows
docs(api): fix typo in getUserById endpoint description
When to Use docs vs Other Types
| Change | Type |
|---|---|
| Update README | docs |
| Add JSDoc comments | docs |
| Fix a typo in a code comment | docs |
| Fix a typo that causes a bug | fix |
| Add a new API endpoint + docs | feat |
| Refactor code + update docs | refactor |
The key rule: if the commit changes only documentation, use docs. If it changes code and documentation together, use the type that describes the code change.
Changelog Behavior
Most changelog generators either exclude docs commits entirely or group them under a separate "Documentation" section. This keeps the changelog focused on user-facing changes while still tracking documentation improvements in the Git history.
Style Tips
- Use the imperative mood: "update guide", not "updated guide."
- Be specific: "update API authentication guide" is better than "update docs."
- Add a scope when the documentation belongs to a specific module.
Use Case
Use docs commits for README updates, API documentation changes, inline comment improvements, and any change that exclusively modifies documentation files without altering the runtime behavior of the application.