Skip to content

Commit 6f3f5f6

Browse files
Leeon-TangLeeon-Tang
committed
refactor: change version management to npm version + git tags - Remove semantic-release/commitlint/husky, update CI to tag-based releases, add .npmignore, update VERSIONING.md, and align versioning with Python setuptools_scm style.
1 parent 3e21a10 commit 6f3f5f6

5 files changed

Lines changed: 262 additions & 1 deletion

File tree

‎.github/workflows/release.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*.*.*'
7+
8+
jobs:
9+
release:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v4
15+
16+
- name: Setup Node.js
17+
uses: actions/setup-node@v4
18+
with:
19+
node-version: '18'
20+
cache: 'npm'
21+
registry-url: 'https://registry.npmjs.org'
22+
23+
- name: Install dependencies
24+
run: npm ci
25+
26+
- name: Run tests
27+
run: npm test
28+
29+
- name: Build project
30+
run: npm run build
31+
32+
- name: Publish to npm
33+
run: npm publish
34+
env:
35+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
36+
37+
- name: Create GitHub Release
38+
uses: actions/create-release@v1
39+
env:
40+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
41+
with:
42+
tag_name: ${{ github.ref }}
43+
release_name: Release ${{ github.ref }}
44+
body: |
45+
Version ${{ github.ref }} has been released.
46+
47+
To install: `npm install wavespeed@${{ github.ref }}`
48+
draft: false
49+
prerelease: false

‎.npmignore‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Source code
2+
src/
3+
examples/
4+
tests/
5+
coverage/
6+
7+
# Development files
8+
.github/
9+
.husky/
10+
jest.config.js
11+
tsconfig.json
12+
.eslintrc.js
13+
.commitlintrc.js
14+
.releaserc.js
15+
16+
# Build artifacts not needed in package
17+
*.tsbuildinfo
18+
*.log
19+
npm-debug.log*
20+
21+
# Dependencies
22+
node_modules/
23+
24+
# OS generated files
25+
.DS_Store
26+
Thumbs.db
27+
28+
# IDE files
29+
.vscode/
30+
.idea/
31+
32+
# CI
33+
.github/

‎VERSIONING.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Versioning with npm version + Git Tags
2+
3+
This project uses `npm version` with Git tags for version management, similar to Python's setuptools_scm approach.
4+
5+
## How it works
6+
7+
- Version numbers are manually managed using `npm version` commands
8+
- Versions are based on Git tags (e.g., `v1.0.0`)
9+
- No automatic version bumping based on commits
10+
- Releases are triggered by creating and pushing Git tags
11+
12+
## Version Format
13+
14+
- **Semantic versioning**: `MAJOR.MINOR.PATCH` (e.g., `1.0.0`)
15+
- **Git tags**: `vMAJOR.MINOR.PATCH` (e.g., `v1.0.0`)
16+
17+
## Creating a Release
18+
19+
### 1. Development Phase
20+
Developers work normally, committing changes to the repository.
21+
22+
### 2. Version Bump (Manual)
23+
When ready to release, use `npm version` to bump the version:
24+
25+
```bash
26+
# Patch version (1.0.0 → 1.0.1)
27+
npm version patch
28+
29+
# Minor version (1.0.0 → 1.1.0)
30+
npm version minor
31+
32+
# Major version (1.0.0 → 2.0.0)
33+
npm version major
34+
35+
# Specific version
36+
npm version 1.2.3
37+
```
38+
39+
### 3. What npm version does
40+
- Updates `package.json` version field
41+
- Creates a Git commit with the version change
42+
- Creates a Git tag (e.g., `v1.0.0`)
43+
- Pushes both commit and tag to remote
44+
45+
### 4. Automated Release
46+
GitHub Actions detects the new tag and automatically:
47+
- Builds the project
48+
- Runs tests
49+
- Publishes to npm
50+
- Creates a GitHub release
51+
52+
## Release Workflow
53+
54+
```bash
55+
# 1. Ensure all changes are committed
56+
git add .
57+
git commit -m "feat: add new feature"
58+
59+
# 2. Bump version (this creates commit + tag)
60+
npm version patch # or minor/major
61+
62+
# 3. Push changes and tag
63+
git push origin main
64+
git push origin --tags
65+
66+
# 4. GitHub Actions automatically publishes
67+
```
68+
69+
## Version Types
70+
71+
| Command | When to use | Example |
72+
|---------|-------------|---------|
73+
| `npm version patch` | Bug fixes, small changes | `1.0.0` → `1.0.1` |
74+
| `npm version minor` | New features, backwards compatible | `1.0.0` → `1.1.0` |
75+
| `npm version major` | Breaking changes | `1.0.0` → `2.0.0` |
76+
77+
## Checking Current Version
78+
79+
```bash
80+
# From package.json
81+
npm version
82+
83+
# Or check npm registry
84+
npm view wavespeed version
85+
86+
# Check latest Git tag
87+
git describe --tags --abbrev=0
88+
```
89+
90+
## GitHub Actions Workflow
91+
92+
The release process is automated when tags are pushed:
93+
94+
```yaml
95+
name: Release
96+
on:
97+
push:
98+
tags:
99+
- 'v*.*.*'
100+
jobs:
101+
release:
102+
runs-on: ubuntu-latest
103+
steps:
104+
- uses: actions/checkout@v4
105+
- uses: actions/setup-node@v4
106+
- run: npm ci
107+
- run: npm test
108+
- run: npm run build
109+
- run: npm publish
110+
- run: Create GitHub release
111+
```
112+
113+
## Pre-release Versions
114+
115+
For beta/rc versions:
116+
117+
```bash
118+
npm version 1.0.0-beta.1
119+
npm version 1.0.0-rc.1
120+
```
121+
122+
## Best Practices
123+
124+
### When to Release
125+
- **Patch releases**: Bug fixes, documentation updates, small improvements
126+
- **Minor releases**: New features that are backwards compatible
127+
- **Major releases**: Breaking changes, API modifications
128+
129+
### Commit Messages
130+
While not strictly enforced, descriptive commit messages are recommended:
131+
132+
```bash
133+
feat: add support for custom timeout options
134+
fix: resolve issue with prediction polling
135+
docs: update API reference documentation
136+
refactor: simplify error handling logic
137+
```
138+
139+
### Version Planning
140+
- Plan version bumps during development
141+
- Test thoroughly before releasing
142+
- Consider deprecation warnings for breaking changes
143+
144+
## Troubleshooting
145+
146+
### Common Issues
147+
148+
1. **Tag already exists**: Delete the tag and try again
149+
```bash
150+
git tag -d v1.0.0
151+
git push origin :refs/tags/v1.0.0
152+
```
153+
154+
2. **Version not updated**: Check if package.json was modified correctly
155+
156+
3. **Publish fails**: Verify NPM_TOKEN permissions and package name uniqueness
157+
158+
### Manual Publish (If needed)
159+
160+
```bash
161+
# Build and test locally
162+
npm run build
163+
npm test
164+
165+
# Publish manually
166+
npm publish
167+
```
168+
169+
## Comparison with Python setuptools_scm
170+
171+
| Aspect | npm version + Git tags | setuptools_scm |
172+
|--------|----------------------|----------------|
173+
| Version source | package.json | Git tags + commit count |
174+
| Version format | 1.2.3 | 1.2.3.dev4+g1234567 |
175+
| Trigger | Manual npm version | Manual git tag |
176+
| Automation | GitHub Actions on tag | Build-time version detection |
177+
| Development versions | Not supported | Automatic dev versions |
178+
179+
This approach provides similar manual control as Python's setuptools_scm while leveraging npm's built-in versioning tools.

‎package-lock.json‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,6 @@
3434
"ts-jest": "^29.1.1",
3535
"typescript": "^5.2.2"
3636
},
37-
"dependencies": {},
3837
"files": [
3938
"dist"
4039
]

0 commit comments

Comments
 (0)