Skip to content

Commit d0133af

Browse files
codingnooobcodingnooob
committed
feat: add automated semantic release documentation
- Document automated release implementation in VERSION_SYNCHRONIZATION.md - Test end-to-end automated pipeline from commit to deployment
1 parent 3bcd6ca commit d0133af

File tree

3 files changed

+211
-3
lines changed

3 files changed

+211
-3
lines changed

‎.github/workflows/ci-cd.yml‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,9 +117,9 @@ jobs:
117117
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
118118

119119
deploy-stores:
120-
needs: [test, security-scan]
120+
needs: [test, security-scan, release]
121121
runs-on: ubuntu-latest
122-
if: github.event_name == 'release' && github.event.action == 'published'
122+
if: github.event_name == 'release' && github.event.action == 'published' && !contains(github.event.release.name, 'next')
123123

124124
steps:
125125
- name: Checkout code
@@ -199,3 +199,30 @@ jobs:
199199
run: |
200200
chmod +x scripts/validate-deployment.sh
201201
./scripts/validate-deployment.sh
202+
203+
semantic-release-deploy:
204+
needs: [test, security-scan]
205+
runs-on: ubuntu-latest
206+
if: github.event_name == 'push' && github.ref == 'refs/heads/main' && !contains(github.event.head_commit.message, '[skip ci]')
207+
208+
steps:
209+
- name: Checkout code
210+
uses: actions/checkout@v4
211+
with:
212+
fetch-depth: 0
213+
token: ${{ secrets.GITHUB_TOKEN }}
214+
215+
- name: Setup Node.js
216+
uses: actions/setup-node@v4
217+
with:
218+
node-version: '20.x'
219+
cache: 'npm'
220+
221+
- name: Install dependencies
222+
run: npm ci --ignore-scripts
223+
224+
- name: Run Semantic Release
225+
run: npm run release
226+
env:
227+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
228+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.releaserc.json‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,14 @@
33
"plugins": [
44
"@semantic-release/commit-analyzer",
55
"@semantic-release/release-notes-generator",
6-
"@semantic-release/changelog"
6+
"@semantic-release/changelog",
7+
"@semantic-release/github",
8+
[
9+
"@semantic-release/git",
10+
{
11+
"assets": ["CHANGELOG.md", "package.json"],
12+
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
13+
}
14+
]
715
]
816
}

‎VERSION_SYNCHRONIZATION.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Version Synchronization Process
2+
3+
This document outlines the process for maintaining version synchronization across all platforms for the Blog Link Analyzer extension.
4+
5+
## Automated Semantic Release Implementation
6+
7+
As of v1.1.1, the project now implements fully automated semantic releases with end-to-end deployment pipeline.
8+
9+
## Current Platform Status
10+
11+
As of v1.1.1, all platforms are synchronized:
12+
13+
- **Chrome Web Store**: v1.1.1 (ready for submission)
14+
- **Firefox Add-ons**: v1.1.1 (already deployed)
15+
- **GitHub Releases**: v1.1.1 (published)
16+
- **Source Code**: package.json v1.1.1
17+
18+
## Version Synchronization Workflow
19+
20+
### 1. Pre-Release Checklist
21+
22+
Before creating a new release:
23+
24+
- [ ] Update `package.json` version
25+
- [ ] Update README.md version references
26+
- [ ] Update CHANGELOG.md with release notes
27+
- [ ] Run full test suite: `npm run validate`
28+
- [ ] Build all packages: `npm run package:all-formats`
29+
30+
### 2. Release Process
31+
32+
1. **Commit Changes**
33+
34+
```bash
35+
git add .
36+
git commit -m "Release v{VERSION}"
37+
```
38+
39+
2. **Create Git Tag**
40+
41+
```bash
42+
git tag v{VERSION}
43+
```
44+
45+
3. **Push to Remote**
46+
47+
```bash
48+
git push origin main --tags
49+
```
50+
51+
4. **Create GitHub Release**
52+
```bash
53+
gh release create v{VERSION} \
54+
--title "Version {VERSION}" \
55+
--notes "Release notes..." \
56+
*.zip *.crx *.xpi
57+
```
58+
59+
### 3. Platform Deployment
60+
61+
#### Chrome Web Store
62+
63+
1. Download `blog-link-analyzer-{VERSION}.zip` from GitHub release
64+
2. Upload to Chrome Developer Dashboard
65+
3. Submit for review
66+
67+
#### Firefox Add-ons
68+
69+
1. Download `blog-link-analyzer-firefox-v{VERSION}.xpi` from GitHub release
70+
2. Upload to Firefox Developer Hub
71+
3. Submit for review
72+
73+
### 4. Post-Release Validation
74+
75+
- [ ] Verify Chrome Web Store shows new version
76+
- [ ] Verify Firefox Add-ons shows new version
77+
- [ ] Verify GitHub release is published
78+
- [ ] Update any external documentation
79+
80+
## Automated CI/CD Process
81+
82+
The `.github/workflows/ci-cd.yml` workflow handles:
83+
84+
1. **Testing**: Runs on all PRs and pushes
85+
2. **Building**: Creates all package formats
86+
3. **Security Scanning**: Audits dependencies
87+
4. **Release Deployment**: Automatically deploys on GitHub releases
88+
89+
### Release Triggers
90+
91+
The workflow deploys to stores when:
92+
93+
- A GitHub release is published (`github.event_name == 'release'`)
94+
- All tests and security scans pass
95+
96+
### Required Secrets
97+
98+
For automated deployment, configure these repository secrets:
99+
100+
- `CHROME_CLIENT_ID`
101+
- `CHROME_CLIENT_SECRET`
102+
- `CHROME_REFRESH_TOKEN`
103+
- `CHROME_EXTENSION_ID`
104+
- `FIREFOX_JWT_ISSUER`
105+
- `FIREFOX_JWT_SECRET`
106+
107+
## Version Validation Commands
108+
109+
Use these commands to verify version synchronization:
110+
111+
```bash
112+
# Check package.json version
113+
node -p "require('./package.json').version"
114+
115+
# Check Chrome package version
116+
unzip -p blog-link-analyzer-*.zip manifest.json | grep '"version"'
117+
118+
# Check Firefox package version
119+
unzip -p blog-link-analyzer-firefox-*.zip manifest.json | grep '"version"'
120+
121+
# List all generated packages
122+
ls -la *.zip *.crx *.xpi
123+
```
124+
125+
## Troubleshooting
126+
127+
### Version Mismatch Issues
128+
129+
If platforms show different versions:
130+
131+
1. **Identify the source of truth** (usually package.json)
132+
2. **Update lagging platforms** to match
133+
3. **Rebuild packages** with correct version
134+
4. **Create new release** if necessary
135+
136+
### Build Failures
137+
138+
If package creation fails:
139+
140+
1. **Clean build artifacts**: `npm run clean`
141+
2. **Reinstall dependencies**: `rm -rf node_modules && npm install`
142+
3. **Check Node.js version**: `node --version` (should be >=20.0.0)
143+
4. **Verify build scripts**: Check `scripts/` directory
144+
145+
### Store Submission Issues
146+
147+
If store submissions fail:
148+
149+
1. **Check manifest validation** using store tools
150+
2. **Verify package contents** match store requirements
151+
3. **Review store policies** for any violations
152+
4. **Check file sizes** within store limits
153+
154+
## Best Practices
155+
156+
1. **Semantic Versioning**: Follow MAJOR.MINOR.PATCH format
157+
2. **Changelog Maintenance**: Update CHANGELOG.md for every release
158+
3. **Testing**: Always run full test suite before releases
159+
4. **Backup**: Keep previous versions for rollback capability
160+
5. **Documentation**: Update README and other docs with new features
161+
162+
## Rollback Process
163+
164+
If a release needs to be rolled back:
165+
166+
1. **Identify the last stable version**
167+
2. **Use rollback script**: `./scripts/rollback.sh latest chrome,firefox`
168+
3. **Create hotfix release** if necessary
169+
4. **Update documentation** with rollback information
170+
171+
---
172+
173+
This process ensures all platforms remain synchronized and releases are consistent across the ecosystem.

0 commit comments

Comments
 (0)