Arc DocsConventional Commits
The dictionary your commits always needed.
We follow the Conventional Commits specification for commit messages.
Angular Commit Format Reference Sheet
General Guideline
- Each commit should be a single logical change. Don't make several logical changes in one commit. For example, if a patch fixes a bug and optimizes the performance of a feature, split it into two separate commits.
- Each commit should be able to stand on its own, and each commit should build on the previous one. This way, if a commit introduces a bug, it should be easy to identify and revert.
- Each commit should be deployable and not break the build, tests, or functionality.
- If you're not sure if a commit should be split, it's better to split it if each commit is deployable and doesn't break the build, tests, or functionality.
- If you fixed changes in a past commit, use
git commit --amendto add changes to the previous commit rather than creating a new one; thus keeping the commit history clean and concise.- Only exception to this is if the commit already existed on the
mainbranch, in which case a fixup commit should be made rather than an amend. If that commit is amended and force pushed to main, it will diverge the git history for the entire team.
- Only exception to this is if the commit already existed on the
- If you ever amend, reorder, or rebase, your local branch will become divergent from the remote for the amended commit(s), so GitHub won't let you push. Simply force push to overwrite your old branch:
git push --force-with-lease.
The slight learning curve of writing conventional commits is well worth the effort. It allows us unlock some pretty powerful DevOps which saves the entire team a lot of time in the long run.
Types
| Label | Description |
|---|---|
fix | A bug fix in the project (e.g., fixing broken links or typos in the docs) |
feat | New feature(s) being added to the project (e.g., adding a new search feature to the docs site) |
docs | A new addition or update to the docs site and/or documentation (e.g., adding a new page explaining a component or updating the API reference) |
test | New tests being added to the project (e.g., Playwright tests to verify the docs site renders correctly on mobile) |
chore | Tasks that don’t modify business logic code and help maintain the project (e.g., reorganizing docs folders, updating docs dependencies, renaming files in the docs site) |
style | Changes that do not affect the meaning of the code and improve readability (e.g., formatting Markdown files, fixing indentation, or adding comments in docs code snippets) |
refactor | A change that improves the readability of code itself without modifying behavior (e.g., cleaning up docs site components, creating helper functions for repeated content) |
perf | A code change that improves performance (e.g., optimizing the docs site build time or loading speed) |
build | Changes that affect the build system or external dependencies (e.g., upgrading the docs site framework or dependencies) |
ci | Changes to CI configuration files and scripts (e.g., adding a script to automatically build or deploy the docs site) |
revert | Reverting a previous commit (e.g., undoing a docs update that broke the site) |
Examples
Here are some examples of commit messages following the decision tree guidelines:
# Bugfix in the Docs site affecting layout
fix(docs): sidebar navigation links not collapsing properly
# Change in a configuration file for the Docs site
chore(docs/config): update ESLint rules for MDX files
# New feature in the Docs site
feat(docs): add search functionality to the knowledge base
# Change in the build process for the Docs site
build(docs): update Next.js config for MDX support
# Change in documentation content
docs(docs): add contribution guidelines for new contributors
# UI improvement in the Docs site
feat(docs): update header search bar styling with hover state
# Performance optimization in the Docs site
perf(docs): reduce image sizes on homepage for faster load times
# Code styling update in the Docs site
style(docs): format markdown tables for consistency
# Refactor in the Docs site
refactor(docs): restructure sidebar items for better organization
# Add or update tests for Docs site components
test(docs): add unit tests for card components