Skip to content

Commit d648c61

Browse files
tip-dtellertip-dteller
committed
docs: add comprehensive semantic-release fix documentation
Add detailed documentation of root cause analysis and solution for semantic-release not triggering releases. Files Added: - RELEASE_FIX_SUMMARY.md: Complete explanation of why releases weren't triggering and how it was fixed with explicit releaseRules Files Updated: - tracking/documentation.md: Document the semantic-release configuration fix work including root cause, solution, and impact Key finding: presetConfig.types only controls changelog visibility (hidden property), not what triggers releases. Explicit releaseRules are required to make docs, security, perf, and refactor commits trigger releases. This documents the solution to issues where properly formatted conventional commits were being ignored by semantic-release. Refs: #13, #14
1 parent 32b1931 commit d648c61

File tree

2 files changed

+278
-0
lines changed

2 files changed

+278
-0
lines changed

‎RELEASE_FIX_SUMMARY.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Semantic-Release Fix Summary
2+
3+
## 🎯 Root Cause Identified
4+
5+
Semantic-release was not triggering releases because `.releaserc.json` was **missing explicit `releaseRules`** in the `@semantic-release/commit-analyzer` plugin configuration.
6+
7+
## 🔍 The Problem
8+
9+
### What We Thought
10+
11+
Initially thought the issue was:
12+
1. ❌ Merge commit format (partially true)
13+
2. ❌ Not on main branch (was also an issue initially)
14+
3. ❌ Squash merge not configured (process issue, not root cause)
15+
16+
### The Real Root Cause
17+
18+
**The `presetConfig.types` configuration only controls CHANGELOG visibility (`hidden` property), NOT what triggers releases!**
19+
20+
```json
21+
// This ONLY affects changelog, NOT releases:
22+
"presetConfig": {
23+
"types": [
24+
{ "type": "docs", "section": "Documentation", "hidden": false }
25+
]
26+
}
27+
```
28+
29+
Without explicit `releaseRules`, semantic-release uses **default rules**:
30+
- `feat:` → minor release ✅
31+
- `fix:` → patch release ✅
32+
- Everything else → **NO RELEASE** ❌
33+
34+
This meant `docs`, `security`, `perf`, and `refactor` commits were **formatted correctly but ignored** for release purposes.
35+
36+
## ✅ The Solution
37+
38+
Added explicit `releaseRules` to `@semantic-release/commit-analyzer`:
39+
40+
```json
41+
"plugins": [
42+
[
43+
"@semantic-release/commit-analyzer",
44+
{
45+
"preset": "conventionalcommits",
46+
"releaseRules": [
47+
{ "type": "feat", "release": "minor" },
48+
{ "type": "fix", "release": "patch" },
49+
{ "type": "security", "release": "patch" }, // NEW
50+
{ "type": "perf", "release": "patch" }, // NEW
51+
{ "type": "docs", "release": "patch" }, // NEW
52+
{ "type": "refactor", "release": "patch" }, // NEW
53+
{ "type": "revert", "release": "patch" }, // NEW
54+
{ "type": "style", "release": false }, // NEW
55+
{ "type": "chore", "release": false" }, // NEW
56+
{ "type": "test", "release": false }, // NEW
57+
{ "type": "build", "release": false }, // NEW
58+
{ "type": "ci", "release": false } // NEW
59+
]
60+
}
61+
]
62+
]
63+
```
64+
65+
## 📊 Commit Types That Now Trigger Releases
66+
67+
| Type | Release Type | Example |
68+
|------|-------------|---------|
69+
| `feat` | Minor (0.X.0) | `feat(atlas): add VPC endpoints` |
70+
| `fix` | Patch (0.0.X) | `fix(database): correct pagination` |
71+
| `security` | Patch (0.0.X) | `security: add credential masking` |
72+
| `perf` | Patch (0.0.X) | `perf(logging): pre-compile regex` |
73+
| `docs` | Patch (0.0.X) | `docs: update installation guide` |
74+
| `refactor` | Patch (0.0.X) | `refactor(api): simplify handlers` |
75+
| `revert` | Patch (0.0.X) | `revert: undo previous change` |
76+
77+
## 📊 Commit Types That DON'T Trigger Releases
78+
79+
| Type | Release | Example |
80+
|------|---------|---------|
81+
| `style` | None | `style: fix formatting` |
82+
| `chore` | None | `chore: update gitignore` |
83+
| `test` | None | `test: add unit tests` |
84+
| `build` | None | `build: update dependencies` |
85+
| `ci` | None | `ci: update workflow` |
86+
87+
## 🔧 Commits Made to Fix
88+
89+
### 1. Commit `b57ac9a` - Initial Fix
90+
```
91+
fix(ci): add releaseRules to commit-analyzer to trigger releases for docs commits
92+
```
93+
- Added releaseRules for docs, perf, refactor, revert
94+
- Fixed the immediate issue preventing docs commits from triggering releases
95+
96+
### 2. Commit `32b1931` - Complete Fix
97+
```
98+
fix(ci): add security type and explicit release rules for all commit types
99+
```
100+
- Added `security` commit type (used in PR #13)
101+
- Added explicit `release: false` for non-releasing types
102+
- Updated PR template with security option
103+
- Updated CONTRIBUTING.md documentation
104+
105+
## 📝 Commits Since Last Release (v4.0.0)
106+
107+
Now semantic-release will analyze:
108+
109+
```
110+
32b1931 fix(ci): add security type and explicit release rules... ✅ PATCH
111+
b57ac9a fix(ci): add releaseRules to commit-analyzer... ✅ PATCH
112+
60e7b56 docs: add squash merge setup guide... ✅ PATCH
113+
c1e06aa docs(ci): enforce squash merge... ✅ PATCH
114+
5c2afcb Fix/security patches (#13) ❌ INVALID (ignored)
115+
------- v4.0.0 (last release)
116+
```
117+
118+
**Result**: Should trigger **v4.0.1** patch release with 4 valid commits in changelog.
119+
120+
## 🎉 Expected Release
121+
122+
After push to main, semantic-release will:
123+
124+
1. **Analyze commits** since v4.0.0
125+
2. **Find valid releases**:
126+
- 2x `fix(ci):` commits → patch release
127+
- 2x `docs:` commits → patch release (now recognized!)
128+
3. **Determine version**: v4.0.1 (patch bump)
129+
4. **Generate changelog**:
130+
- Bug Fixes section (2 CI fixes)
131+
- Documentation section (2 docs updates)
132+
5. **Create GitHub release** with binaries attached
133+
134+
## 📚 Documentation Updates
135+
136+
### Files Updated
137+
138+
1. **`.releaserc.json`** - Added complete releaseRules
139+
2. **`.github/CONTRIBUTING.md`** - Added security type to table
140+
3. **`.github/pull_request_template.md`** - Added security checkbox
141+
4. **`tracking/documentation.md`** - Tracked this work (TODO)
142+
143+
### Process Improvements
144+
145+
1. **Squash merge enforced** - GitHub configured, PR template guides contributors
146+
2. **Explicit release rules** - No ambiguity about what triggers releases
147+
3. **Security commit type** - Now officially supported
148+
4. **Complete documentation** - CONTRIBUTING.md has full commit type table
149+
150+
## 🚀 Verification Steps
151+
152+
1. **Check GitHub Actions**: https://github.com/teabranch/matlas-cli/actions
153+
2. **Look for Release workflow** triggered by the push
154+
3. **Check semantic-release logs** for:
155+
```
156+
[semantic-release] [@semantic-release/commit-analyzer] › ℹ Analyzing commit: fix(ci)...
157+
[semantic-release] [@semantic-release/commit-analyzer] › ℹ The release type for the commit is patch
158+
[semantic-release] › ℹ The next release version is 4.0.1
159+
```
160+
4. **Verify new release created**: https://github.com/teabranch/matlas-cli/releases
161+
162+
## 💡 Key Learnings
163+
164+
1. **`presetConfig.types` ≠ `releaseRules`**
165+
- `presetConfig.types` only controls changelog sections
166+
- `releaseRules` controls what triggers releases
167+
168+
2. **Always use explicit releaseRules**
169+
- Don't rely on preset defaults
170+
- Make release behavior explicit and documented
171+
172+
3. **Squash merge is a process issue**
173+
- It helps ensure clean commit messages
174+
- But doesn't fix underlying configuration issues
175+
- Both are needed: proper config + proper process
176+
177+
4. **Security is a valid commit type**
178+
- Though not in standard Conventional Commits spec
179+
- Many projects use it for security-related changes
180+
- Now properly configured and documented
181+
182+
## 📖 References
183+
184+
- [Conventional Commits Specification](https://www.conventionalcommits.org/)
185+
- [semantic-release Documentation](https://semantic-release.gitbook.io/)
186+
- [commit-analyzer Plugin](https://github.com/semantic-release/commit-analyzer)
187+
- [conventionalcommits Preset](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits)
188+
189+
---
190+
191+
**Status**: ✅ Fixed and pushed to main
192+
**Expected Release**: v4.0.1 (patch)
193+
**Next Steps**: Monitor GitHub Actions for release creation

‎tracking/documentation.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,3 +125,88 @@ gh repo edit teabranch/matlas-cli \
125125
```
126126

127127
---
128+
129+
## [2025-12-11] Semantic-Release Configuration Fix
130+
131+
**Status**: Completed
132+
**Developer**: Danny Teller / Assistant
133+
**Related Issues**: #13, #14 - semantic-release not triggering despite properly formatted commits
134+
135+
### Summary
136+
Fixed semantic-release configuration by adding explicit releaseRules to the commit-analyzer plugin. The root cause was that presetConfig.types only controls changelog visibility, not what triggers releases.
137+
138+
### Tasks
139+
- [x] Identify root cause of release failures
140+
- [x] Add releaseRules to @semantic-release/commit-analyzer
141+
- [x] Add security commit type support
142+
- [x] Update PR template with security type
143+
- [x] Update CONTRIBUTING.md with complete commit type table
144+
- [x] Create comprehensive summary documentation
145+
146+
### Files Modified
147+
- `.releaserc.json` - Added complete releaseRules configuration
148+
- `.github/CONTRIBUTING.md` - Added security type to commit types table
149+
- `.github/pull_request_template.md` - Added security checkbox option
150+
- `RELEASE_FIX_SUMMARY.md` - NEW: Complete documentation of root cause and solution
151+
- `tracking/documentation.md` - Added this tracking entry
152+
153+
### Root Cause
154+
155+
The `.releaserc.json` configuration had `presetConfig.types` but no explicit `releaseRules` in the commit-analyzer plugin. This caused semantic-release to use default rules which only trigger releases for `feat` and `fix` commits.
156+
157+
**Key Discovery**: `presetConfig.types` only controls:
158+
- What sections appear in the changelog
159+
- Whether commits are hidden (hidden: true/false)
160+
161+
It does NOT control what triggers releases. That requires explicit `releaseRules`.
162+
163+
### Solution Implemented
164+
165+
Added explicit `releaseRules` to `@semantic-release/commit-analyzer`:
166+
167+
**Commits that trigger releases:**
168+
- feat → minor (0.X.0)
169+
- fix → patch (0.0.X)
170+
- security → patch (0.0.X) [NEW]
171+
- perf → patch (0.0.X) [NEW]
172+
- docs → patch (0.0.X) [NEW]
173+
- refactor → patch (0.0.X) [NEW]
174+
- revert → patch (0.0.X) [NEW]
175+
176+
**Commits that don't trigger releases:**
177+
- style → release: false
178+
- chore → release: false
179+
- test → release: false
180+
- build → release: false
181+
- ci → release: false
182+
183+
### Commits Made
184+
185+
1. `b57ac9a` - fix(ci): add releaseRules to commit-analyzer to trigger releases for docs commits
186+
2. `32b1931` - fix(ci): add security type and explicit release rules for all commit types
187+
188+
### Impact
189+
190+
Now all properly formatted conventional commits will correctly trigger releases:
191+
- docs commits (like PR #14) will trigger patch releases
192+
- security commits (like in PR #13) will trigger patch releases
193+
- perf commits (like in PR #13) will trigger patch releases
194+
- Previous docs/perf/security commits were properly formatted but ignored
195+
196+
### Expected Result
197+
198+
Push to main should trigger v4.0.1 release including:
199+
- 2 CI fixes (releaseRules additions)
200+
- 2 documentation updates (squash merge docs)
201+
- Changelog with both Bug Fixes and Documentation sections
202+
203+
### Notes
204+
205+
This explains why:
206+
1. PR #13 didn't trigger a release (bad merge commit format + missing releaseRules)
207+
2. PR #14 didn't trigger a release (missing releaseRules for docs type)
208+
3. Manual commit amendments didn't help (still missing releaseRules)
209+
210+
The squash merge configuration is still valuable for ensuring clean commit messages, but it couldn't fix the underlying missing releaseRules configuration.
211+
212+
---

0 commit comments

Comments
 (0)