Skip to content

Commit 64cd2e4

Browse files
alexpmulealexpmule
committed
docs: add commitlint and Conventional Commits guidelines to branch naming conventions
- Added comprehensive section on commit message format (enforced by commitlint) - Documented all valid commit types (feat, fix, docs, etc.) - Provided good vs bad examples - Clarified that commitlint validates messages, NOT branch names - Updated comparison table to include commit message format - Added validation tips and troubleshooting Related: W-21315032
1 parent 686eb2b commit 64cd2e4

1 file changed

Lines changed: 168 additions & 5 deletions

File tree

‎docs/team/patterns/branch-naming-conventions.md‎

Lines changed: 168 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,154 @@ Different branch naming patterns are used depending on the type of change and re
1717

1818
---
1919

20+
## Commit Message Conventions (Enforced by commitlint)
21+
22+
### Overview
23+
24+
**This repository uses commitlint** with `@commitlint/config-conventional` to enforce standardized commit messages.
25+
26+
**Configuration**: `commitlint.config.js`
27+
28+
**What commitlint validates**:
29+
- ✅ Commit message **format** (type, scope, subject)
30+
- ❌ **NOT** branch names (branch names are flexible)
31+
32+
### Conventional Commits Format
33+
34+
```
35+
<type>(<scope>): <subject>
36+
37+
[optional body]
38+
39+
[optional footer]
40+
```
41+
42+
**Example**:
43+
```
44+
fix(api-navigation): resolve deep allOf property collection
45+
46+
Added recursive traversal for nested allOf chains.
47+
48+
Related: W-21368901
49+
```
50+
51+
### Valid Commit Types
52+
53+
| Type | Use When | Example |
54+
|------|----------|---------|
55+
| `feat` | New feature | `feat(api-request): add OAuth2 PKCE support` |
56+
| `fix` | Bug fix | `fix(api-documentation): resolve markdown rendering issue` |
57+
| `docs` | Documentation only | `docs: update README with new examples` |
58+
| `style` | Code formatting (no logic change) | `style: fix indentation in ApiConsole.js` |
59+
| `refactor` | Code refactor (no bug fix or feature) | `refactor: extract AMF helper into separate file` |
60+
| `test` | Test changes | `test: add regression test for deep allOf` |
61+
| `chore` | Maintenance tasks | `chore: bump version to 6.6.62` |
62+
| `perf` | Performance improvement | `perf: optimize AMF model traversal` |
63+
| `ci` | CI/CD changes | `ci: update GitHub Actions workflow` |
64+
| `build` | Build system changes | `build: update rollup config` |
65+
| `revert` | Revert previous commit | `revert: revert "feat: add feature X"` |
66+
67+
### Scope (Optional but Recommended)
68+
69+
Scope indicates what part of the codebase is affected:
70+
71+
**Examples**:
72+
- `fix(api-navigation):` - Navigation component
73+
- `feat(api-request):` - Request panel
74+
- `docs(README):` - README file
75+
- `chore(deps):` - Dependencies
76+
77+
**When to omit scope**:
78+
- Changes affect entire codebase
79+
- Documentation updates at root level
80+
- Version bumps
81+
82+
### Subject Line Rules
83+
84+
✅ **DO**:
85+
- Use imperative mood ("add" not "added" or "adds")
86+
- Start with lowercase
87+
- No period at the end
88+
- Keep under 72 characters
89+
90+
❌ **DON'T**:
91+
- Start with uppercase
92+
- End with period
93+
- Use past tense
94+
- Be vague ("fix stuff", "update things")
95+
96+
### Examples: Good vs Bad
97+
98+
#### ✅ Good Commits
99+
100+
```bash
101+
fix(api-navigation): resolve deep allOf property collection
102+
feat(api-request): add OAuth2 PKCE support
103+
docs: add branch naming conventions pattern
104+
chore: bump version to 6.6.62
105+
test: add regression test for deep allOf schemas
106+
refactor(api-console): extract AMF helper utilities
107+
```
108+
109+
#### ❌ Bad Commits (will fail commitlint)
110+
111+
```bash
112+
Fixed bug # Missing type/scope, past tense
113+
Update code. # Vague, ends with period
114+
FEAT: Add feature # Uppercase type, uppercase subject
115+
fix stuff # Too vague
116+
Added new feature to navigation # Past tense
117+
```
118+
119+
### Body and Footer (Optional)
120+
121+
**Body**: Detailed explanation of WHAT changed and WHY (not HOW - code shows that)
122+
123+
**Footer**: Reference tickets, breaking changes, etc.
124+
125+
**Example**:
126+
```
127+
fix(api-example-generator): add recursive property collection for deep allOf
128+
129+
Single-pass iteration through allOf shapes didn't recursively expand
130+
nested shacl:and arrays beyond 3 levels. This caused properties in
131+
4+ level allOf chains to be missing from generated examples.
132+
133+
Added _collectPropertiesRecursive() method with:
134+
- Depth limiting (max 10 levels)
135+
- Circular reference detection
136+
- Backward compatibility
137+
138+
Related: W-21368901
139+
Closes: #123
140+
```
141+
142+
### Validation
143+
144+
**commitlint runs automatically**:
145+
- On `git commit` (via husky pre-commit hook, if configured)
146+
- In CI/CD pipeline
147+
148+
**Test commit message locally**:
149+
```bash
150+
echo "fix(api-console): resolve issue" | npx commitlint
151+
```
152+
153+
**If validation fails**:
154+
```bash
155+
⧗ input: update code
156+
✖ subject may not be empty [subject-empty]
157+
✖ type may not be empty [type-empty]
158+
✖ found 2 problems, 0 warnings
159+
```
160+
161+
Fix the commit message:
162+
```bash
163+
git commit --amend -m "fix(api-console): resolve navigation issue"
164+
```
165+
166+
---
167+
20168
## Branch Naming Patterns
21169

22170
### 1. `fix/W-XXXXX-description` - Component Bug Fixes
@@ -129,11 +277,13 @@ build/6.7.0 # Minor version bump
129277

130278
## Comparison Table
131279

132-
| Scenario | Branch Pattern | Repo | Version Bump in Branch? | Example |
133-
|----------|----------------|------|-------------------------|---------|
134-
| Fix bug in component | `fix/W-XXXXX-desc` | `@api-components/*` | ❌ No | `fix/W-21368901-deep-allof` |
135-
| Release api-console | `build/X.X.X` | `mulesoft/api-console` | ✅ Yes (`npm version patch`) | `build/6.6.62` |
136-
| Update wrapper | `X.X.X` | `mulesoft-emu/anypoint-api-console` | ❌ No | `6.6.88` |
280+
| Scenario | Branch Pattern | Repo | Version Bump in Branch? | Commit Message Format | Example |
281+
|----------|----------------|------|-------------------------|-----------------------|---------|
282+
| Fix bug in component | `fix/W-XXXXX-desc` | `@api-components/*` | ❌ No | ✅ Conventional Commits | `fix/W-21368901-deep-allof` |
283+
| Release api-console | `build/X.X.X` | `mulesoft/api-console` | ✅ Yes (`npm version patch`) | ✅ Conventional Commits | `build/6.6.62` |
284+
| Update wrapper | `X.X.X` | `mulesoft-emu/anypoint-api-console` | ❌ No | ✅ Conventional Commits | `6.6.88` |
285+
286+
**Note**: Commit messages are validated by commitlint in ALL repos, regardless of branch naming pattern.
137287

138288
---
139289

@@ -150,6 +300,19 @@ If we used `fix/` branches in api-console and ran `npm version patch` in each:
150300
- **api-console**: `build/` branches bundle multiple components, explicit version in branch name prevents conflicts
151301
- **Wrapper**: Direct version number, independent versioning
152302

303+
### Note on commitlint
304+
305+
**commitlint validates commit messages, NOT branch names.**
306+
307+
- ✅ Branch names: `fix/W-12345-bug`, `build/6.6.62`, `feat/my-feature` - **ALL valid**
308+
- ✅ Commit messages: **MUST** follow Conventional Commits format (enforced)
309+
310+
**Why this matters**:
311+
- Branch names are flexible and team-specific
312+
- Commit messages are standardized across projects (tooling compatibility)
313+
- Git history benefits from consistent commit message format
314+
- Branch names are temporary (deleted after merge), commit messages are permanent
315+
153316
---
154317

155318
## Related GUS Work Items

0 commit comments

Comments
 (0)