Skip to content

Commit 05d4b22

Browse files
andi1984andi1984
authored
Merge pull request #736 from andi1984/claude/semantic-version-workflow-014uE2SWUpx6VjbRz8qnHkpG
Build semantic versioning GitHub Actions workflow
2 parents 2a5dcc6 + 5df1a5a commit 05d4b22

4 files changed

Lines changed: 779 additions & 3 deletions

File tree

‎.github/workflows/RELEASE.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
# Automated Release Workflow
2+
3+
This document explains the automated release workflow for the VS Code TinyPNG extension.
4+
5+
## Overview
6+
7+
The release workflow automates the entire release process:
8+
1. Analyzes commits using conventional commit standards
9+
2. Determines the appropriate semantic version bump (major, minor, patch)
10+
3. Updates `package.json` with the new version
11+
4. Generates/updates `CHANGELOG.md` automatically
12+
5. Creates a Git tag for the release
13+
6. Publishes the extension to the VS Code Marketplace
14+
7. Creates a GitHub Release with release notes
15+
16+
## Setup Requirements
17+
18+
### 1. VS Code Marketplace Token (VSCE_PAT)
19+
20+
To enable automatic publishing to the VS Code Marketplace, you need to set up a Personal Access Token:
21+
22+
1. **Create a Personal Access Token:**
23+
- Go to https://dev.azure.com/
24+
- Navigate to User Settings > Personal Access Tokens
25+
- Click "New Token"
26+
- Name: `vscode-tinypng-release`
27+
- Organization: `All accessible organizations`
28+
- Scopes: Select `Marketplace` > `Manage`
29+
- Click "Create"
30+
31+
2. **Add the token to GitHub Secrets:**
32+
- Go to your GitHub repository
33+
- Navigate to Settings > Secrets and variables > Actions
34+
- Click "New repository secret"
35+
- Name: `VSCE_PAT`
36+
- Value: Paste your Azure DevOps Personal Access Token
37+
- Click "Add secret"
38+
39+
### 2. GitHub Token
40+
41+
The workflow uses `GITHUB_TOKEN` which is automatically provided by GitHub Actions. No additional setup required.
42+
43+
## Conventional Commits
44+
45+
The workflow uses conventional commits to automatically determine the version bump type:
46+
47+
### Commit Message Format
48+
49+
```
50+
<type>(<scope>): <subject>
51+
52+
<body>
53+
54+
<footer>
55+
```
56+
57+
### Version Bump Rules
58+
59+
| Commit Type | Version Bump | Example |
60+
|-------------|--------------|---------|
61+
| `feat:` | **minor** (0.x.0) | `feat: add WebP compression support` |
62+
| `fix:` | **patch** (0.0.x) | `fix: resolve file encoding issue` |
63+
| `BREAKING CHANGE:` or `!` | **major** (x.0.0) | `feat!: remove deprecated API` |
64+
| `chore:`, `docs:`, `refactor:` | **patch** (0.0.x) | `chore: update dependencies` |
65+
66+
### Examples
67+
68+
**Minor version bump (new feature):**
69+
```
70+
feat: add queue system for batch compression
71+
72+
Implements a concurrent queue system that processes
73+
multiple images efficiently with configurable concurrency.
74+
```
75+
76+
**Patch version bump (bug fix):**
77+
```
78+
fix: prevent duplicate compressions in queue
79+
80+
Fixes an issue where the same file could be added
81+
to the compression queue multiple times.
82+
```
83+
84+
**Major version bump (breaking change):**
85+
```
86+
feat!: redesign compression API
87+
88+
BREAKING CHANGE: The compression service now requires
89+
async/await syntax instead of callbacks.
90+
```
91+
92+
## Usage
93+
94+
### Triggering a Release
95+
96+
1. **Navigate to GitHub Actions:**
97+
- Go to your repository on GitHub
98+
- Click on the "Actions" tab
99+
- Select "Release" workflow from the left sidebar
100+
101+
2. **Run the workflow:**
102+
- Click "Run workflow" button
103+
- Configure options:
104+
- **Branch:** Select the branch to release from (usually `develop` or `main`)
105+
- **Version bump type:** Leave empty for auto-detection or manually select major/minor/patch
106+
- **Dry run:** Check this to test the workflow without actually publishing
107+
- Click "Run workflow"
108+
109+
### Workflow Options
110+
111+
#### Version Type (Optional)
112+
- **Empty (default):** Automatically detect version bump from commits
113+
- **major:** Force a major version bump (e.g., 1.0.0 → 2.0.0)
114+
- **minor:** Force a minor version bump (e.g., 1.0.0 → 1.1.0)
115+
- **patch:** Force a patch version bump (e.g., 1.0.0 → 1.0.1)
116+
117+
#### Dry Run
118+
- **false (default):** Execute full release including publishing
119+
- **true:** Test the workflow without publishing or pushing changes
120+
121+
## Workflow Steps
122+
123+
The workflow performs the following steps:
124+
125+
1. **Checkout & Setup**
126+
- Checks out the repository with full history
127+
- Sets up Node.js 22 with npm caching
128+
129+
2. **Build & Test**
130+
- Installs dependencies
131+
- Compiles TypeScript
132+
- Runs the test suite
133+
134+
3. **Version Analysis**
135+
- Retrieves current version from `package.json`
136+
- Gets the latest Git tag
137+
- Analyzes commits since last tag
138+
- Determines version bump type (unless manually specified)
139+
- Calculates new version number
140+
141+
4. **Update Files**
142+
- Updates `package.json` with new version
143+
- Updates `package-lock.json`
144+
- Generates/updates `CHANGELOG.md` using conventional changelog format
145+
146+
5. **Commit & Tag**
147+
- Commits version bump and changelog changes
148+
- Creates a Git tag (e.g., `v1.4.0`)
149+
- Pushes changes and tags to GitHub
150+
151+
6. **Package & Publish**
152+
- Packages the extension as `.vsix` file
153+
- Publishes to VS Code Marketplace (if `VSCE_PAT` is configured)
154+
155+
7. **GitHub Release**
156+
- Extracts relevant changelog section
157+
- Creates a GitHub Release with release notes
158+
- Attaches `.vsix` file to the release
159+
160+
## Best Practices
161+
162+
### 1. Use Conventional Commits
163+
Always use conventional commit messages for your commits. This ensures accurate version bumping.
164+
165+
```bash
166+
# Good
167+
git commit -m "feat: add new compression algorithm"
168+
git commit -m "fix: resolve memory leak in queue service"
169+
170+
# Bad
171+
git commit -m "updated stuff"
172+
git commit -m "bug fixes"
173+
```
174+
175+
### 2. Test with Dry Run First
176+
Before doing an actual release, run the workflow with dry run enabled to verify:
177+
- Version bump is correct
178+
- CHANGELOG looks good
179+
- No errors in the process
180+
181+
### 3. Release from Develop Branch
182+
Maintain a stable `develop` branch and trigger releases from it. This ensures:
183+
- All tests pass
184+
- Code is reviewed
185+
- Features are complete
186+
187+
### 4. Review Generated Changelog
188+
After the workflow completes, review the generated CHANGELOG.md to ensure:
189+
- All important changes are documented
190+
- Formatting is correct
191+
- No sensitive information is exposed
192+
193+
## Troubleshooting
194+
195+
### Publication Fails
196+
197+
**Error:** `VSCE_PAT secret not set`
198+
- **Solution:** Add `VSCE_PAT` secret to repository settings (see Setup Requirements)
199+
200+
**Error:** `Authentication failed`
201+
- **Solution:** Verify your Personal Access Token is valid and has Marketplace permissions
202+
203+
### Version Not Bumped
204+
205+
**Issue:** Workflow runs but version stays the same
206+
- **Cause:** No conventional commits found since last tag
207+
- **Solution:** Ensure commits follow conventional commit format, or manually specify version type
208+
209+
### Tests Fail
210+
211+
**Issue:** Workflow fails at test step
212+
- **Cause:** Breaking changes or failing tests in the codebase
213+
- **Solution:** Fix tests before releasing, or skip tests (not recommended)
214+
215+
### Push Rejected
216+
217+
**Error:** `failed to push some refs`
218+
- **Cause:** Protected branch or outdated local branch
219+
- **Solution:** Ensure branch protection rules allow GitHub Actions to push
220+
221+
## Manual Release (Fallback)
222+
223+
If the automated workflow fails, you can still release manually:
224+
225+
```bash
226+
# 1. Update version
227+
npm version patch|minor|major
228+
229+
# 2. Update CHANGELOG
230+
conventional-changelog -p angular -i CHANGELOG.md -s
231+
232+
# 3. Commit and tag
233+
git add .
234+
git commit -m "chore(release): vX.Y.Z"
235+
git tag vX.Y.Z
236+
237+
# 4. Push
238+
git push origin develop
239+
git push origin --tags
240+
241+
# 5. Publish
242+
vsce login
243+
vsce publish
244+
245+
# 6. Create GitHub release manually
246+
```
247+
248+
## Monitoring
249+
250+
### Workflow Status
251+
Monitor workflow runs in the Actions tab:
252+
- Green checkmark: Successful release
253+
- Red X: Failed release (check logs)
254+
- Yellow dot: In progress
255+
256+
### View Logs
257+
Click on a workflow run to see detailed logs for each step.
258+
259+
### Notifications
260+
Configure GitHub notifications to receive alerts when workflows complete or fail.
261+
262+
## Security
263+
264+
- Never commit `VSCE_PAT` or other secrets to the repository
265+
- Use GitHub Secrets for sensitive tokens
266+
- Review workflow permissions regularly
267+
- Audit published versions for security issues
268+
269+
## Support
270+
271+
If you encounter issues with the release workflow:
272+
1. Check the workflow logs in GitHub Actions
273+
2. Review this documentation
274+
3. Check conventional-changelog and vsce documentation
275+
4. Open an issue in the repository

0 commit comments

Comments
 (0)