Cursor rule

1---
2description: When running git commit
3alwaysApply: false
4version: 1.0.0
5---
6 
7# Git Commit Message Guidelines
8 
9We write commit messages to communicate with our future selves and teammates. A great
10commit message tells the story of why we made a change, making code archaeology easier
11and helping others understand our reasoning and thought process.
12 
13## Core Principles
14 
15- Reflect on the full change before writing the message
16- Focus on motivation and reasoning, not just what changed (the diff shows that)
17- Scale message length to change importance and size - simple changes get one line,
18  major architectural changes deserve 2-3 paragraphs
19- Use imperative mood ("Add feature" not "Added feature")
20- Summary line under 72 characters, no period at the end
21- Capitalize the first word after any emoji
22 
23## No-Deploy Marker
24 
25For changes that should not trigger deployment (documentation, tests, CI config, etc.),
26include `[no-deploy]` in the commit message. This signals both humans and CI/CD
27automation that deployment is unnecessary.
28 
29Place the marker either:
30 
31- At the end of the summary line if it fits:
32  `Update README with installation steps [no-deploy]`
33- On its own line after the summary for longer messages
34 
35## Emoji Usage
36 
37You have complete freedom to choose ANY emoji that adds value. Start with gitmoji as
38your reference - if there's a clear gitmoji match, use it. But feel free to get creative
39and use any emoji that genuinely enhances meaning or clarity.
40 
41Include an emoji when it:
42 
43- Makes commit history more scannable at a glance
44- Provides instant visual categorization of the change type
45- Creates useful visual anchors in git log
46- Adds personality or context that words alone miss
47 
48Skip the emoji entirely when it would feel forced or add no real value. Many excellent
49commit messages need no emoji at all.
50 
51Trust your judgment on which emoji fits best, or whether to use one at all.
52 
53## Structure
54 
55```
56[optional emoji] Summary line under 72 characters
57 
58[Optional body when context is needed]
59```
60 
61Body is optional. Include when explaining why adds value beyond the summary and diff.
62When included: explain motivation, problem being solved, impact, trade-offs, or
63alternatives considered. Wrap at 72 characters. For large/important changes, write 2-3
64paragraphs if needed.
65 
66## Examples
67 
68Simple change (no body needed):
69 
70```
71🐛 Handle null values in user preferences
72```
73 
74Simple documentation change (no deploy):
75 
76```
77Fix typo in API documentation [no-deploy]
78```
79 
80Medium change with context:
81 
82```
83♻️ Extract validation logic into shared module
84 
85Validation was duplicated across registration, profile updates, and
86admin tools with slight variations causing inconsistent behavior.
87Consolidating into a shared module ensures consistency and makes
88future validation changes easier.
89```
90 
91Documentation with body (no deploy on separate line):
92 
93```
94📝 Update deployment guide with environment variables
95[no-deploy]
96 
97Added missing DATABASE_POOL_SIZE and CACHE_TTL variables that were
98causing confusion during staging deployments. Also clarified the
99difference between development and production configurations.
100```
101 
102Large architectural change (2-3 paragraphs for major changes):
103 
104```
105🏗️ Migrate from REST to event-driven architecture
106 
107Replace synchronous REST endpoints with event-driven processing to
108support real-time features and improve system resilience...
109 
110Previous architecture required services to block waiting for responses,
111creating cascading failures and poor user experience during high load.
112Events allow asynchronous processing and natural retry mechanisms...
113 
114This change affects order processing, notification system, and analytics
115pipeline. Services can now scale independently and handle partial
116failures gracefully. Trade-off: eventual consistency instead of
117immediate, but business requirements allow 2-3 second delay...
118```
119 
120## Guidelines
121 
122Write messages that future developers will thank you for. Use present tense imperative
123mood. Skip conventional commit prefixes like feat: or fix: (gitmoji serves this purpose
124when needed). Include body text only when it adds meaningful context. Write clearly and
125directly for human readers.
126 
127The goal is clarity and kindness to our future selves and teammates. Every commit
128message is a small act of documentation that either helps or hinders. We choose to help.
129