Skip to content

Commit d8b83e8

Browse files
alvagantealvagante
committed
Added RELEASE DOCS
1 parent 9e94926 commit d8b83e8

1 file changed

Lines changed: 293 additions & 0 deletions

File tree

‎docs/VERSION-MANAGEMENT.md‎

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
# Version Management Guide
2+
3+
## How Versioning Works
4+
5+
This project uses `setuptools_scm` for automatic version management based on git tags.
6+
7+
## Version Format
8+
9+
```
10+
{tag}.post{distance}+{local}
11+
```
12+
13+
- **tag**: Git tag (e.g., `v0.1.0` → `0.1.0`)
14+
- **post{distance}**: Number of commits after the tag
15+
- **+{local}**: Local modifications indicator (e.g., `+dirty`)
16+
17+
## Examples
18+
19+
| Git State | Version | Meaning |
20+
|-----------|---------|---------|
21+
| At tag `v0.1.0`, clean | `0.1.0` | Clean release |
22+
| At tag `v0.1.0`, modified | `0.1.0+dirty` | Release with uncommitted changes |
23+
| 5 commits after `v0.1.0`, clean | `0.1.0.post5` | Development version |
24+
| 5 commits after `v0.1.0`, modified | `0.1.0.post5+dirty` | Development with changes |
25+
| No tags, 57 commits | `0.0.post57` | Pre-release development |
26+
27+
## Creating a Release
28+
29+
### Step 1: Commit All Changes
30+
31+
```bash
32+
# Check status
33+
git status
34+
35+
# Commit everything
36+
git add .
37+
git commit -m "Release 0.1.0: Description of changes"
38+
```
39+
40+
### Step 2: Create Git Tag
41+
42+
```bash
43+
# Create annotated tag
44+
git tag -a v0.1.0 -m "Release version 0.1.0"
45+
46+
# Or simple tag
47+
git tag v0.1.0
48+
```
49+
50+
### Step 3: Reinstall Packages
51+
52+
```bash
53+
# Uninstall old versions
54+
pip uninstall -y sai saigen
55+
56+
# Clean build artifacts
57+
make clean
58+
59+
# Install fresh
60+
make install-both
61+
```
62+
63+
### Step 4: Verify Version
64+
65+
```bash
66+
sai --version
67+
# Output: sai, version 0.1.0
68+
69+
saigen --version
70+
# Output: saigen, version 0.1.0
71+
```
72+
73+
### Step 5: Push to Remote (Optional)
74+
75+
```bash
76+
# Push commits
77+
git push origin main
78+
79+
# Push tag
80+
git push origin v0.1.0
81+
```
82+
83+
## Updating a Tag
84+
85+
If you need to move a tag to a different commit:
86+
87+
```bash
88+
# Delete local tag
89+
git tag -d v0.1.0
90+
91+
# Create new tag at current commit
92+
git tag v0.1.0
93+
94+
# Force push to remote (if already pushed)
95+
git push origin v0.1.0 --force
96+
```
97+
98+
## Understanding +dirty Suffix
99+
100+
The `+dirty` suffix appears when you have:
101+
- Modified files (tracked or untracked)
102+
- Staged but uncommitted changes
103+
- Any difference from the tagged commit
104+
105+
### Why It's Useful
106+
107+
- **Safety**: Prevents confusion between released and development code
108+
- **Traceability**: Shows the code doesn't exactly match the tag
109+
- **Development**: Helps identify working copies vs releases
110+
111+
### To Remove +dirty
112+
113+
Simply commit your changes:
114+
115+
```bash
116+
git add .
117+
git commit -m "Your commit message"
118+
pip uninstall -y sai saigen
119+
make install-both
120+
```
121+
122+
## Configuration
123+
124+
The versioning is configured in `pyproject.toml`:
125+
126+
```toml
127+
[tool.setuptools_scm]
128+
root = ".." # Look for git repo in parent dir
129+
write_to = "sai/_version.py" # Write version to this file
130+
version_scheme = "post-release" # Use post-release versioning
131+
local_scheme = "dirty-tag" # Add +dirty for uncommitted changes
132+
```
133+
134+
### Important: _version.py Files
135+
136+
The `_version.py` files are **auto-generated** and should NOT be tracked in git:
137+
138+
```bash
139+
# Already in .gitignore
140+
*/_version.py
141+
_version.py
142+
```
143+
144+
These files are created during installation and contain the calculated version.
145+
146+
## Version Bumping Strategies
147+
148+
### Patch Release (0.1.0 → 0.1.1)
149+
150+
```bash
151+
git add .
152+
git commit -m "Fix: Description"
153+
git tag v0.1.1
154+
pip uninstall -y sai saigen && make install-both
155+
```
156+
157+
### Minor Release (0.1.0 → 0.2.0)
158+
159+
```bash
160+
git add .
161+
git commit -m "Feature: Description"
162+
git tag v0.2.0
163+
pip uninstall -y sai saigen && make install-both
164+
```
165+
166+
### Major Release (0.1.0 → 1.0.0)
167+
168+
```bash
169+
git add .
170+
git commit -m "Breaking: Description"
171+
git tag v1.0.0
172+
pip uninstall -y sai saigen && make install-both
173+
```
174+
175+
## Using the Release Script
176+
177+
The project includes a release automation script:
178+
179+
```bash
180+
# Patch bump (0.1.0 → 0.1.1)
181+
python scripts/release.py patch
182+
183+
# Minor bump (0.1.0 → 0.2.0)
184+
python scripts/release.py minor
185+
186+
# Major bump (0.1.0 → 1.0.0)
187+
python scripts/release.py major
188+
189+
# Dry run (see what would happen)
190+
python scripts/release.py patch --dry-run
191+
```
192+
193+
The script automatically:
194+
1. Runs tests
195+
2. Updates changelog
196+
3. Creates git tag
197+
4. Builds packages
198+
5. Optionally publishes to PyPI
199+
200+
## Troubleshooting
201+
202+
### Version Still Shows +dirty After Committing
203+
204+
Check if `_version.py` files are modified:
205+
206+
```bash
207+
git status
208+
# If you see sai/_version.py or saigen/_version.py modified:
209+
210+
# They should be in .gitignore
211+
git rm --cached sai/_version.py saigen/_version.py
212+
git commit -m "Remove auto-generated _version.py from tracking"
213+
git tag -d v0.1.0
214+
git tag v0.1.0
215+
pip uninstall -y sai saigen && make install-both
216+
```
217+
218+
### Version Shows 0.0.postXX
219+
220+
No git tags exist. Create one:
221+
222+
```bash
223+
git tag v0.1.0
224+
pip uninstall -y sai saigen && make install-both
225+
```
226+
227+
### Version Shows Wrong Number
228+
229+
Check your tags:
230+
231+
```bash
232+
# List all tags
233+
git tag -l
234+
235+
# See which tag is most recent
236+
git describe --tags
237+
238+
# Delete wrong tag
239+
git tag -d v0.2.0
240+
241+
# Create correct tag
242+
git tag v0.1.0
243+
```
244+
245+
### Want to Disable +dirty Suffix
246+
247+
Change `local_scheme` in both `pyproject.toml` files:
248+
249+
```toml
250+
[tool.setuptools_scm]
251+
local_scheme = "no-local-version" # Instead of "dirty-tag"
252+
```
253+
254+
**Not recommended** - the +dirty suffix is useful for development.
255+
256+
## Best Practices
257+
258+
1. **Always commit before tagging** - Ensures clean version
259+
2. **Use annotated tags** - `git tag -a v0.1.0 -m "Message"`
260+
3. **Follow semantic versioning** - MAJOR.MINOR.PATCH
261+
4. **Update changelog** - Document what changed
262+
5. **Test before tagging** - Run `make test`
263+
6. **Don't track _version.py** - Let setuptools_scm generate it
264+
265+
## Quick Reference
266+
267+
```bash
268+
# Create release
269+
git add . && git commit -m "Release 0.1.0" && git tag v0.1.0
270+
271+
# Reinstall
272+
pip uninstall -y sai saigen && make install-both
273+
274+
# Check version
275+
sai --version && saigen --version
276+
277+
# Push release
278+
git push origin main && git push origin v0.1.0
279+
```
280+
281+
## Related Files
282+
283+
- `sai/pyproject.toml` - SAI version configuration
284+
- `saigen/pyproject.toml` - SAIGEN version configuration
285+
- `scripts/release.py` - Automated release script
286+
- `.gitignore` - Excludes `_version.py` files
287+
- `CHANGELOG.md` - Version history
288+
289+
## Further Reading
290+
291+
- [setuptools_scm documentation](https://github.com/pypa/setuptools_scm)
292+
- [Semantic Versioning](https://semver.org/)
293+
- [Git Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)

0 commit comments

Comments
 (0)