docs: Documentation Changes
Learn how to write commit messages for documentation-only changes using the docs type. Covers README updates, API docs, inline comments, and contribution guides.
Detailed Explanation
The docs Commit Type
The docs type is used when your commit only modifies documentation. This includes README files, API documentation, inline code comments, contribution guides, changelogs, and any other written content that does not affect the runtime behavior of the application. Under Semantic Versioning, docs commits do not trigger any version bump since they do not change the software itself.
Example Messages
docs: add API authentication section to README
docs: fix typo in contributing guidelines
docs(api): document rate limiting headers
When to Use docs
Use docs when your commit:
- Updates the README or other markdown files
- Adds or improves JSDoc, Javadoc, or docstring comments
- Updates API reference documentation
- Modifies contribution or setup guides
- Fixes typos, grammar, or formatting in documentation
- Adds architecture decision records (ADRs)
When NOT to Use docs
If your commit changes code and documentation, use the type that matches the code change. For example, if you add a new feature and update the README to document it, use feat and mention the docs update in the body.
With Scope
Adding a scope helps clarify which documentation was updated:
docs(changelog): add entries for v2.3.0 release
docs(readme): add Docker deployment instructions
This is especially useful in monorepos or projects with multiple documentation areas.
Use Case
You have updated the project's README to include new setup instructions for Docker-based development. The code itself has not changed at all, only the documentation files. You need a commit message that makes it clear this is a docs-only change so reviewers and CI pipelines can treat it accordingly.