Source | Embedded Intelligence Bureau
In our embedded software development process, Git has become the core infrastructure for team collaboration. However, casual commit messages (such as <span>git commit -m "fix bug!"</span>) often lead to difficulties in tracing history and reduced collaboration efficiency. Here, I will introduce the practical implementation of Structured Commit Standards, which significantly enhance the maintainability of the codebase through template configuration, standardized fields, and visual operations.
1. Background: Why Do We Need Commit Standards?
-
Pain Points of Information Loss A brief single-line commit can only describe “what was changed” and fails to reflect:
- Type of change (feature addition/bug fix/refactor)
- Scope of impact (inter-module dependencies)
- Self-testing verification status
- Related requirements or bug tracking
Team Collaboration Costs According to incomplete statistics, developers spend an average of 15% of their time tracing code history. Chaotic commit records can lead to:
- Difficulties in version rollback
- Low efficiency in code auditing
- Increased onboarding costs for newcomers
Therefore, commit standards are indeed very important for engineering projects. So how should we implement them?
2. Designing Commit Standard Templates
Below are some fields and explanations that I find useful and am currently using:
| Field | Required | Description and Example |
|---|---|---|
| Type | Yes | <span>feat</span> (feature addition) / <span>fix</span> (bug fix) / <span>refactor</span> (refactor) / <span>docs</span> (documentation), etc. |
| Subject | Yes | A summary of no more than 50 characters, such as:<span>feat: Add CAN bus timeout retransmission mechanism</span> |
| Change Content | Yes | Specific modification location:<span>Added retry_counter field in drivers/can/can_core.c</span> |
| Scope of Impact | Yes | Related modules:<span>Affects the initialization process of can_parser and can_monitor modules</span> |
| Self-testing Status | Yes | Verification method:<span>Verified 100% success rate of retransmission through can_unit_test for 100 times</span> |
| Related Links | No | Requirement/Bug link:<span>JIRA: EMB-2075</span> |
Template file example (save as
<span>~/.git_commit_example</span>):<type>: <subject> Change content: Scope of impact: Self-testing status: Related links:
3. Configuration and Usage
3.1 Template Configuration
# Global configuration (recommended)
git config --global commit.template ~/.git_commit_example
# Single repository configuration
cd to the corresponding path
git config commit.example ~/.git_commit_example
3.2 Editor Settings
# Global default editor
git config --global core.editor vim
3.3 Commit Process
-
Add changes to the staging area
<span>git add drivers/can/can_core.c</span> -
Trigger template editing
<span>git commit</span>→ Automatically load the template file At this point, Vim opens the template interface: -
Fill in the standardized information
fix: Fix CAN bus data parity error Change content: Modified the parity algorithm on line 203 of can_core.c Scope of impact: All modules dependent on the CAN driver Self-testing status: Passed hardware loopback test for 2000 frames of data Related links: BUG#EMB-3056
Subsequently, you can quickly filter feature commits by type using<span>git log --grep="^feat"</span>.
Commit standards are not merely formalism; they are a lever for engineering efficiency.
———— END ————
Some of the most challenging stages for programmers!
Principles of the commonly used state machine QP framework in microcontrollers
In-depth analysis of the OTA transmission protocol for microcontrollers