Documentation explains software behavior, usage, implementation, or relevant reference information. In collaborative development, it carries context that code alone cannot: why a change exists, how it should be reviewed, and what others need to do next. section 2.3.2 section 8.2
Use documentation to make work understandable and reviewable:
- Add feature documentation when introducing a new capability, and reference relevant technical or user documentation when reviewers need more context. section 2.3.2
- Record context, justification, use cases, testing, previews, linked issues, and before-and-after comparisons according to the change type. section 2.3.2
- Define whether missing documentation blocks approval, whether explanatory comments count, and which documentation types belong in review. section 3.3.2
- Document operational procedures before and after execution, including authorization, actions taken, deviations, affected tools, temporary access, timing, and justification. section 10.2.2 section 10.2.4
- Treat preparation as part of development rather than an optional burden; clear documentation helps reviewers understand changes and can reduce review delays. section 8.2
Emergency Procedure Execution Record
After an emergency bypass, create an execution record containing who acted, what happened, which temporary controls and tools were affected, when and where it occurred, the justification, and any deviations from the planned steps. Follow it with communication and postincident analysis. section 10.2.4
Table 2.2 Description elements based on categorization prefix
|
If you used this categorization prefix in the title:
|
These are some expected components to place in the description:
|
|---|---|
feat:
Alternatives:
feat(component or project): feature: feature(component or project): |
Context/justification
Use cases
How has this been tested?
Preview (if applicable)
Documentation
Tests
|
fix:
|
Context/justification
Linked Issue/ticket #
Before-/after-fix comparison
How to test it
Documentation
Tests
|
docs:
|
Context/justification
Linked Issue/ticket #
Use cases
Preview (if applicable)
|
chore:
|
Context/justification
|
breaking:
|
Context/justification
How has this been tested?
Affected projects
Important dates
Mitigation/next steps
Documentation
Tests
|
Use the categorization prefix to choose a practical pull-request description checklist: feature changes emphasize context, use cases, testing, previews, documentation, and tests; fixes add issue links and before-and-after comparisons; breaking changes add affected projects, dates, mitigation, documentation, and tests. section 2.3.2
