Skip to content

Commit 6fa62d9

Browse files
aaronlippoldaaronlippold
committed
ci: add comprehensive release workflow and documentation
- Add GitHub Actions release workflow with npm publishing - Add release script with --dry-run and --help options - Add detailed release process documentation - Configure automated releases on tag push (v*) - Support beta/alpha/rc release tags - Use SAF_NPM_TOKEN for npm authentication - Add provenance to npm publishes Follows Nuxt module release patterns with changelogen support. Authored by: Aaron Lippold<lippold@gmail.com>
1 parent fa015ec commit 6fa62d9

File tree

3 files changed

+421
-0
lines changed

3 files changed

+421
-0
lines changed

‎.github/workflows/release.yml

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: write
11+
id-token: write
12+
13+
jobs:
14+
release:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v5
18+
with:
19+
fetch-depth: 0
20+
21+
- uses: pnpm/action-setup@v4
22+
with:
23+
version: 9
24+
25+
- uses: actions/setup-node@v4
26+
with:
27+
node-version: 20
28+
registry-url: 'https://registry.npmjs.org'
29+
cache: pnpm
30+
31+
- name: Install dependencies
32+
run: pnpm install --frozen-lockfile
33+
34+
- name: Run tests
35+
run: pnpm test
36+
37+
- name: Run linter
38+
run: pnpm lint
39+
40+
- name: Build module
41+
run: pnpm prepack
42+
43+
- name: Publish to npm
44+
run: |
45+
if [[ "${{ github.ref }}" == *"-beta"* ]]; then
46+
npm publish --provenance --tag beta
47+
elif [[ "${{ github.ref }}" == *"-alpha"* ]]; then
48+
npm publish --provenance --tag alpha
49+
else
50+
npm publish --provenance
51+
fi
52+
env:
53+
NODE_AUTH_TOKEN: ${{ secrets.SAF_NPM_TOKEN }}
54+
55+
- name: Create GitHub Release
56+
env:
57+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
58+
run: |
59+
gh release create ${{ github.ref_name }} \
60+
--title "${{ github.ref_name }}" \
61+
--notes-file CHANGELOG.md \
62+
${{ contains(github.ref, '-beta') || contains(github.ref, '-alpha') && '--prerelease' || '' }}

‎docs/contributing/release-process.md

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Release Process
2+
3+
This document describes the release process for nuxt-smartscript.
4+
5+
## Overview
6+
7+
We use [changelogen](https://github.com/unjs/changelogen) for automated versioning and changelog generation, following the patterns established by other Nuxt modules.
8+
9+
## Prerequisites
10+
11+
Before releasing:
12+
1. Ensure you have push access to the repository
13+
2. Ensure you have npm publish rights for the package
14+
3. Set up `SAF_NPM_TOKEN` as a GitHub secret for automated publishing
15+
16+
## Release Types
17+
18+
- **Patch Release** (0.1.0 → 0.1.1): Bug fixes and minor updates
19+
- **Minor Release** (0.1.0 → 0.2.0): New features, backward compatible
20+
- **Major Release** (0.x.x → 1.0.0): Breaking changes or stable API
21+
- **Beta Release** (0.1.0 → 0.1.1-beta.1): Pre-release for testing
22+
23+
## How Releases Work
24+
25+
Our release process follows this flow:
26+
27+
1. **Developer creates a git tag** (manually or via changelogen)
28+
2. **Tag is pushed to GitHub**
29+
3. **GitHub Actions workflow triggers** on tag push (v*)
30+
4. **Workflow automatically**:
31+
- Runs tests and linting
32+
- Builds the module
33+
- Publishes to npm with provenance
34+
- Creates GitHub release with changelog
35+
36+
## Manual Release Process
37+
38+
### 1. Using npm script with changelogen (Recommended)
39+
40+
```bash
41+
# Standard release (patch/minor/major based on commits)
42+
pnpm release
43+
44+
# Specific version bump
45+
pnpm release -- --patch
46+
pnpm release -- --minor
47+
pnpm release -- --major
48+
49+
# Pre-release versions
50+
pnpm release -- --prerelease
51+
pnpm release -- --prerelease beta
52+
```
53+
54+
This will:
55+
1. Run tests and linting
56+
2. Build the module
57+
3. Update version in package.json
58+
4. Generate/update CHANGELOG.md
59+
5. Create git commit and tag
60+
6. Push to GitHub
61+
7. Publish to npm
62+
63+
### 2. Using release script
64+
65+
```bash
66+
# Make script executable (first time only)
67+
chmod +x scripts/release.sh
68+
69+
# Run release
70+
./scripts/release.sh patch # or minor, major, etc.
71+
```
72+
73+
### 3. Manual steps
74+
75+
If you need more control:
76+
77+
```bash
78+
# 1. Ensure main branch is up to date
79+
git checkout main
80+
git pull origin main
81+
82+
# 2. Run tests
83+
pnpm test
84+
pnpm lint
85+
86+
# 3. Build
87+
pnpm prepack
88+
89+
# 4. Use changelogen to handle versioning
90+
pnpm changelogen --release
91+
92+
# 5. Review and edit CHANGELOG.md if needed
93+
# Then push with tags
94+
git push origin main --follow-tags
95+
96+
# 6. Publish to npm
97+
npm publish
98+
```
99+
100+
## Automated Release (GitHub Actions)
101+
102+
When you push a tag starting with `v`, GitHub Actions will automatically:
103+
104+
1. Run all tests
105+
2. Build the module
106+
3. Publish to npm with provenance
107+
4. Create a GitHub release
108+
109+
```bash
110+
# After using changelogen or manual tagging
111+
git push origin v0.1.0
112+
```
113+
114+
## Beta Releases
115+
116+
For beta testing:
117+
118+
```bash
119+
# Create beta version
120+
pnpm changelogen --prerelease beta
121+
122+
# Push tag
123+
git push origin v0.1.1-beta.1
124+
125+
# This will publish to npm with beta tag
126+
# Users install with: npm install nuxt-smartscript@beta
127+
```
128+
129+
## Post-Release Checklist
130+
131+
After releasing:
132+
133+
- [ ] Verify npm package is published: https://www.npmjs.com/package/nuxt-smartscript
134+
- [ ] Check GitHub release was created: https://github.com/mitre/nuxt-smartscript/releases
135+
- [ ] Test installation in a fresh project
136+
- [ ] Update documentation if needed
137+
- [ ] Announce release if significant
138+
139+
## Troubleshooting
140+
141+
### npm publish fails
142+
143+
1. Check npm authentication: `npm whoami`
144+
2. Ensure you have publish rights: `npm owner ls nuxt-smartscript`
145+
3. Check if SAF_NPM_TOKEN is set in GitHub secrets
146+
147+
### GitHub release not created
148+
149+
1. Check GitHub Actions: https://github.com/mitre/nuxt-smartscript/actions
150+
2. Ensure GITHUB_TOKEN has write permissions
151+
3. Verify tag format starts with 'v'
152+
153+
### Tests fail during release
154+
155+
1. Run tests locally: `pnpm test`
156+
2. Check for uncommitted changes
157+
3. Ensure dependencies are up to date: `pnpm update`
158+
159+
## Version Guidelines
160+
161+
Follow semantic versioning:
162+
163+
- **0.x.x**: Pre-stable releases (current phase)
164+
- API may change between minor versions
165+
- Use for initial development and feedback gathering
166+
167+
- **1.0.0**: First stable release
168+
- API is stable
169+
- Breaking changes only in major versions
170+
- Ready for production use
171+
172+
- **Beta/Alpha tags**
173+
- Use for testing new features
174+
- Not recommended for production
175+
- May have breaking changes
176+
177+
## Changelog Conventions
178+
179+
We follow [Conventional Commits](https://www.conventionalcommits.org/):
180+
181+
- `feat:` New features → minor version bump
182+
- `fix:` Bug fixes → patch version bump
183+
- `docs:` Documentation only
184+
- `chore:` Maintenance tasks
185+
- `test:` Test improvements
186+
- `perf:` Performance improvements
187+
- `refactor:` Code refactoring
188+
- `BREAKING CHANGE:` → major version bump
189+
190+
Changelogen automatically parses these and updates CHANGELOG.md accordingly.

0 commit comments

Comments
 (0)