Skip to content

Commit 5406a21

Browse files
Lokesh-Garg-22Lokesh-Garg-22
authored
feat: add automated release workflow (#16)
Add GitHub Actions workflow for automated releases to VS Code Marketplace with version management, changelog updates, and automatic rollback on failure. - Automated CHANGELOG.md updates from [Unreleased] section - Version bumping (major/minor/patch) - VS Code Marketplace publishing - GitHub Release creation with custom formatting - Complete rollback protection - Add release workflow documentation
1 parent 53296c3 commit 5406a21

4 files changed

Lines changed: 590 additions & 9 deletions

File tree

‎.github/RELEASE_WORKFLOW.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# Release Workflow Guide
2+
3+
This document explains how to use the automated release workflow for the
4+
CSS/SCSS Modules IntelliSense extension.
5+
6+
## 🚀 Quick Start
7+
8+
### Quick Steps to Release
9+
10+
1. **Update CHANGELOG.md** - Add your changes under `[Unreleased]`:
11+
12+
```markdown
13+
## [Unreleased]
14+
15+
### Added
16+
17+
- Your new features
18+
19+
### Fixed
20+
21+
- Your bug fixes
22+
```
23+
24+
2. **Go to GitHub Actions**
25+
26+
- Visit: <https://github.com/Lokesh-Garg-22/CSS-Modules-IntelliSense/actions>
27+
- Click "Release and Publish"
28+
- Click "Run workflow"
29+
30+
3. **Select Version Type**
31+
32+
- `patch` → Bug fixes (0.1.4 → 0.1.5)
33+
- `minor` → New features (0.1.4 → 0.2.0)
34+
- `major` → Breaking changes (0.1.4 → 1.0.0)
35+
36+
4. **Click "Run workflow"** ✅
37+
38+
### What Happens Automatically
39+
40+
- ✅ Updates CHANGELOG.md
41+
- ✅ Bumps package.json version
42+
- ✅ Runs tests
43+
- ✅ Creates git tag
44+
- ✅ Publishes to VS Code Marketplace
45+
- ✅ Creates GitHub Release
46+
- ❌ **Rolls back everything if anything fails!**
47+
48+
---
49+
50+
## Overview
51+
52+
The `release.yml` GitHub Actions workflow automates the entire release process:
53+
54+
1. ✅ Updates CHANGELOG.md from `[Unreleased]` to versioned release
55+
2. ✅ Bumps version in package.json
56+
3. ✅ Runs compilation and tests
57+
4. ✅ Creates a git tag with release notes
58+
5. ✅ Publishes to VS Code Marketplace
59+
6. ✅ Creates a GitHub Release with VSIX file
60+
7. ✅ **Automatic rollback** if anything fails
61+
62+
## Prerequisites
63+
64+
### 1. Setup VS Code Marketplace Token
65+
66+
You need a Personal Access Token (PAT) from Visual Studio Marketplace:
67+
68+
1. Go to [https://dev.azure.com/](https://dev.azure.com/)
69+
2. Click on your profile → Security → Personal Access Tokens
70+
3. Create a new token with:
71+
- **Organization:** All accessible organizations
72+
- **Scopes:** Marketplace → Manage
73+
4. Copy the token
74+
75+
### 2. Add Secret to GitHub
76+
77+
1. Go to your GitHub repository
78+
2. Settings → Secrets and variables → Actions
79+
3. Click "New repository secret"
80+
4. Name: `VSCE_PAT`
81+
5. Value: Paste your token
82+
6. Click "Add secret"
83+
84+
## How to Release
85+
86+
### Step 1: Add Changes to CHANGELOG
87+
88+
Before releasing, ensure your `CHANGELOG.md` has
89+
an `[Unreleased]` section with your changes:
90+
91+
```markdown
92+
## [Unreleased]
93+
94+
### Added
95+
96+
- New feature descriptions
97+
98+
### Changed
99+
100+
- Modified functionality
101+
102+
### Fixed
103+
104+
- Bug fixes
105+
```
106+
107+
### Step 2: Trigger the Workflow
108+
109+
1. Go to your GitHub repository
110+
2. Click on **Actions** tab
111+
3. Select **Release and Publish** workflow
112+
4. Click **Run workflow** button
113+
5. Select version type:
114+
- **patch** (0.1.4 → 0.1.5) - Bug fixes
115+
- **minor** (0.1.4 → 0.2.0) - New features
116+
- **major** (0.1.4 → 1.0.0) - Breaking changes
117+
6. Click **Run workflow**
118+
119+
### Step 3: Monitor Progress
120+
121+
The workflow will:
122+
123+
- ⏳ Extract changes from `[Unreleased]`
124+
- ⏳ Update CHANGELOG.md and package.json
125+
- ⏳ Run tests
126+
- ⏳ Create git tag
127+
- ⏳ Publish to marketplace
128+
- ⏳ Create GitHub release
129+
130+
### Step 4: Verify Release
131+
132+
Once complete, verify:
133+
134+
- ✅ New version appears on [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=lokesh-garg.css-scss-modules-intellisense)
135+
- ✅ GitHub release created with tag
136+
- ✅ CHANGELOG.md updated
137+
- ✅ package.json version bumped
138+
139+
## What Happens on Failure?
140+
141+
If **any step fails**, the workflow automatically:
142+
143+
1. ❌ Restores original package.json and CHANGELOG.md
144+
2. ❌ Resets git to the commit before the workflow ran
145+
3. ❌ Deletes any created tags (local and remote)
146+
4. ❌ Force pushes to reset the remote branch
147+
5. ❌ Exits with an error message
148+
149+
**You can safely retry after fixing the issue!**
150+
151+
## Workflow Steps Detail
152+
153+
### Version Calculation
154+
155+
- **Current version:** Read from package.json
156+
- **New version:** Calculated based on semver (major.minor.patch)
157+
158+
### CHANGELOG Update
159+
160+
```markdown
161+
## [Unreleased]
162+
163+
## [0.1.5] – 2025-12-02
164+
165+
### Added
166+
167+
- Your changes here
168+
```
169+
170+
The workflow:
171+
172+
1. Keeps `[Unreleased]` section header (empty for next release)
173+
2. Converts previous unreleased content to new version
174+
3. Adds comparison link at bottom
175+
176+
### Tag Creation
177+
178+
- Tag name: `v{version}` (e.g., `v0.1.5`)
179+
- Tag message: Content from `[Unreleased]` section
180+
- Pushed to remote repository
181+
182+
### Publishing
183+
184+
- Packages extension as `.vsix` file
185+
- Publishes to VS Code Marketplace using `vsce publish`
186+
- Uploads `.vsix` to GitHub Release
187+
188+
## Troubleshooting
189+
190+
### "No [Unreleased] section found"
191+
192+
**Solution:** Add an `[Unreleased]` section to CHANGELOG.md with your changes
193+
194+
### "No changes found in [Unreleased] section"
195+
196+
**Solution:** Add at least one change under the `[Unreleased]` heading
197+
198+
### "VSCE_PAT secret not found"
199+
200+
**Solution:** Add your Visual Studio Marketplace token as a GitHub secret (see Prerequisites)
201+
202+
### "Tests failed"
203+
204+
**Solution:** Fix test failures locally first, then retry the workflow
205+
206+
### "Permission denied" errors
207+
208+
**Solution:** Ensure the workflow has write permissions in repository settings
209+
210+
## Manual Rollback
211+
212+
If you need to manually rollback a release:
213+
214+
```bash
215+
# Delete local tag
216+
git tag -d v0.1.5
217+
218+
# Delete remote tag
219+
git push origin :refs/tags/v0.1.5
220+
221+
# Reset to previous commit
222+
git reset --hard HEAD~1
223+
git push origin main --force
224+
```
225+
226+
Then manually revert CHANGELOG.md and package.json changes.
227+
228+
## Best Practices
229+
230+
1. **Always test locally** before releasing
231+
2. **Keep [Unreleased] section updated** as you make changes
232+
3. **Use semantic versioning** appropriately:
233+
- patch: backwards-compatible bug fixes
234+
- minor: backwards-compatible new features
235+
- major: breaking changes
236+
4. **Review the CHANGELOG** before triggering release
237+
5. **Monitor the workflow** in Actions tab during release
238+
239+
## Version History Format
240+
241+
The CHANGELOG follows [Keep a Changelog](https://keepachangelog.com/) format:
242+
243+
```markdown
244+
## [Unreleased]
245+
246+
## [0.2.0] – 2025-12-15
247+
248+
### Added
249+
250+
- New feature
251+
252+
## [0.1.5] – 2025-12-02
253+
254+
### Fixed
255+
256+
- Bug fix
257+
```
258+
259+
## GitHub Actions Limits
260+
261+
- Public repositories: Unlimited minutes
262+
- Private repositories: 2,000 minutes/month (free tier)
263+
- Workflow typically takes 3-5 minutes
264+
265+
## Security
266+
267+
- **Never commit** your VSCE_PAT token to the repository
268+
- Use GitHub Secrets for sensitive data
269+
- Tokens are masked in workflow logs
270+
- Review workflow permissions regularly

0 commit comments

Comments
 (0)