Cognitive overhead is the extra mental effort reviewers spend resolving avoidable uncertainty before they can evaluate a change. In code review, vague pull request titles create questions, navigation, and distraction instead of quickly establishing the change’s purpose. section 2.3.1
Two titles, two review paths
“Bug fix for invoice issue” leaves reviewers wondering which invoice problem is involved, how urgent it is, and whether a ticket exists. “Fix issue #1462” merely moves the work elsewhere: reviewers must open the issue, search its discussion, and recover their original purpose. A useful title should make the pull request understandable before the reviewer reads it in full. section 2.3.1
Table 2.1 PR title categorization prefixes
|
Categorization prefix
|
Use for
|
Examples
|
|---|---|---|
feat:
Alternatives:
feat(component or project):
feature:
feature(component or project):
|
Features, ideally complete, atomic, and encapsulated portions or behaviors
When dealing with large projects or multiple components, it can be helpful to specify the affected component or project as part of the prefix.
|
feat: add common timeouts to registry/digest/head fetches
feat: add axis option to slide transition
feat(sidenav): customize width using percentages
feature: add oci image index support via Accepted headers
|
fix:
|
Bug fixes, hot fixes
Code intended to fix unintended or unwanted behavior.
When dealing with large projects or multiple components, it can be helpful to specify the affected component or project as part of the prefix.
|
fix: remove links to nonexistent resources in sitemap
fix: omit a11y warning on <video> when aria-hidden="true"
fix(svelte:element): race condition with transition #7948
fix(flags): detect schedule set from env
fix: blinking cursor in <Select> on IE11
fix: always add missing slashes to link names
fix(registry): image name parsing behavior
|
docs:
|
Anything related to documentation: additions, deprecations, updates to examples, spelling and grammar fixes, improvements to reading flow, etc.
|
docs: add "HTTP API Mode" link to nav menu
docs(js): update Scrollspy documentation example
docs: fix typo in getting started
docs: change wording "finished" to "refined" in context api example
|
chore:
|
Code changes that deal with developer maintenance tasks or ecosystem changes
Think dependency upgrades, fixing lint rules, reorganizing tests, CI/CD pipeline modifications, and other similar changes
|
chore(deps): bump alpine from 3.17.3 to 3.18.0 in /dockerfiles
chore: add missing types to compiler/compile/render_dom functions and variables
chore: upgrade to eslint 8
chore: a11y tests cleanup
chore(ci): run code coverage on main push
chore: move textarea tests to the correct place
|
breaking:
|
Significant code changes that alter core functionality, drift from previous implementations, remove functionality, or change major dependencies
These are code changes that you want to highlight.
|
breaking: make transitions local by default
breaking: set version to 4, remove engines.pnpm and bump engines.node to >=16
breaking: remove legacy package.json files
breaking: remove the deprecated hooks, methods and options for version 13.0.0
breaking: refactor Walkontable Selection rendering module
|
Use title categorization prefixes to make a change’s purpose and affected area easier to identify at a glance. section 2.3.1
