Skip to content

Commit ba3b38d

Browse files
djdarcydjdarcy
committed
v0.2.2: feat: add update-common.sh, VERSION, sync-versions docs
Added: - update-common.sh: subtree management script for consuming projects (pull, --check version status, --push local changes upstream) - VERSION file (0.2.2) for simple version tracking across subtrees - docs/sync-versions.md: reference doc for version management system (configuration, PEP 440 mapping, hooks integration, all flags) Fixed: - demo/build_demo.py, demo_render.py: fix parent path resolution after move into demo/ subdirectory (parent.parent -> parent.parent.parent) Removed: - .github/workflows/ci.yml, release.yml: template leftovers that always fail (this repo isn't a pip-installable package) - tests/test_version.py: template placeholder with $PACKAGE_NAME that never worked in this repo (test structure kept for future use) Refs #1 (consumer tracking)
1 parent 1c8501e commit ba3b38d

9 files changed

Lines changed: 285 additions & 191 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 0 additions & 74 deletions
This file was deleted.

‎.github/workflows/release.yml‎

Lines changed: 0 additions & 56 deletions
This file was deleted.

‎README.md‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,9 @@ bash scripts/install-hooks.sh
2020
Update to latest:
2121

2222
```bash
23-
git subtree pull --prefix=scripts repokit-common main --squash
24-
```
25-
26-
Push local improvements back upstream:
27-
28-
```bash
29-
git subtree push --prefix=scripts repokit-common main
23+
bash scripts/update-common.sh # pull latest
24+
bash scripts/update-common.sh --check # check if behind upstream
25+
bash scripts/update-common.sh --push # push local changes upstream
3026
```
3127

3228
## What's Included
@@ -37,7 +33,7 @@ git subtree push --prefix=scripts repokit-common main
3733
- **pre-push** -- Python syntax check, pytest, debug statement detection
3834

3935
### Version Management
40-
- **sync-versions.py** -- Single source of truth for version bumping with git metadata (branch, build count, date, hash)
36+
- **sync-versions.py** -- Single source of truth for version bumping with git metadata. See [docs/sync-versions.md](docs/sync-versions.md) for full reference.
4137
- **update-version.sh** -- Legacy bash version updater (deprecated; use sync-versions.py)
4238

4339
### GitHub Tools

‎VERSION‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
0.2.2

‎demo/build_demo.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@
2727

2828
# -- Configuration --
2929

30-
PROJECT_ROOT = Path(__file__).resolve().parent.parent
31-
DEFAULT_TAPE = PROJECT_ROOT / "scripts" / "vhs" / "demo.tape"
30+
PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
31+
DEFAULT_TAPE = PROJECT_ROOT / "scripts" / "demo" / "vhs" / "demo.tape"
3232
DEFAULT_OUTPUT = PROJECT_ROOT / "docs" / "demo.gif"
3333

3434
# Common binary locations (checked in order)

‎demo/demo_render.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
from pathlib import Path
2020

2121
# Add project root to path so we can import the render module
22-
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
22+
sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
2323

2424
# TODO: Replace with your project's render imports
2525
# from your_package.output.render import render_diagnosis, render_history

‎docs/sync-versions.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# sync-versions.py
2+
3+
Single source of truth for version management across DazzleTools projects.
4+
5+
## Overview
6+
7+
`sync-versions.py` reads version components from `_version.py` and propagates them to:
8+
- The `__version__` string (with git metadata: branch, build count, date, commit hash)
9+
- CHANGELOG.md compare links
10+
11+
It replaces manual version editing. Git hooks call it automatically on every commit.
12+
13+
## How It Works
14+
15+
### The Version File (`_version.py`)
16+
17+
Every project has a `_version.py` in its package directory. This is the canonical source:
18+
19+
```python
20+
# Version components - edit these for version bumps
21+
MAJOR = 0
22+
MINOR = 3
23+
PATCH = 0
24+
PHASE = "" # "" (stable), "alpha", "beta", "rc1"
25+
PROJECT_PHASE = "" # "prealpha", "alpha", "beta", "stable"
26+
27+
# Auto-updated by git hooks - do not edit manually
28+
__version__ = "0.3.0_main_12-20260404-a1b2c3d4"
29+
__app_name__ = "my-project"
30+
```
31+
32+
**You edit:** `MAJOR`, `MINOR`, `PATCH`, `PHASE`, `PROJECT_PHASE`
33+
**Hooks update:** `__version__`, `PIP_VERSION`, `VERSION`, etc.
34+
35+
### The `__version__` String Format
36+
37+
```
38+
MAJOR.MINOR.PATCH[-PHASE]_BRANCH_BUILD-YYYYMMDD-COMMITHASH
39+
```
40+
41+
Examples:
42+
- `0.3.0_main_12-20260404-a1b2c3d4` -- stable, 12th build on main
43+
- `0.3.0-alpha_dev_5-20260401-b2c3d4e5` -- alpha phase, 5th build on dev
44+
45+
### Version Levels
46+
47+
| Level | Scope | Changes when... | Example |
48+
|-------|-------|-----------------|---------|
49+
| `PHASE` | Per-MINOR feature set | Feature set matures: `"alpha"` -> `"beta"` -> `""` | `0.3.0-alpha` -> `0.3.0` |
50+
| `PROJECT_PHASE` | Entire project | Project hits maturity threshold (rare) | `PREALPHA 0.3.0` -> `BETA 0.5.0` |
51+
52+
`PHASE` resets with each MINOR bump. `PROJECT_PHASE` is independent of version numbers.
53+
54+
## Configuration
55+
56+
In `pyproject.toml`:
57+
58+
```toml
59+
[tool.repokit-common]
60+
version-source = "my_package/_version.py"
61+
changelog = "CHANGELOG.md"
62+
repo-url = "https://github.com/MyOrg/my-project"
63+
tag-prefix = "v"
64+
tag-format = "pep440" # or "human"
65+
private-patterns = ["private/", "local/", ".env"]
66+
```
67+
68+
### Tag Format
69+
70+
| Setting | Tag example | PEP 440 | Use when |
71+
|---------|-------------|---------|----------|
72+
| `"pep440"` (default) | `v0.3.0a1` | `0.3.0a1` | Publishing to PyPI |
73+
| `"human"` | `v0.3.0-alpha` | N/A | Human-readable tags, not on PyPI |
74+
75+
For stable releases (no phase), both produce identical tags: `v0.3.0`.
76+
77+
## Usage
78+
79+
### Check if versions are in sync
80+
81+
```bash
82+
python scripts/sync-versions.py --check
83+
```
84+
85+
Reports `[OK]` or `[X]` for each managed file. Returns exit code 1 if out of sync.
86+
87+
### Sync without changing version
88+
89+
```bash
90+
python scripts/sync-versions.py
91+
```
92+
93+
Updates `__version__` with current git metadata (branch, build count, date, hash). Run this after manual edits to `_version.py`.
94+
95+
### Bump version
96+
97+
```bash
98+
python scripts/sync-versions.py --bump patch # 0.3.0 -> 0.3.1
99+
python scripts/sync-versions.py --bump minor # 0.3.0 -> 0.4.0
100+
python scripts/sync-versions.py --bump major # 0.3.0 -> 1.0.0
101+
```
102+
103+
### Set version directly
104+
105+
```bash
106+
python scripts/sync-versions.py --set 1.0.0
107+
```
108+
109+
### Change phase
110+
111+
```bash
112+
python scripts/sync-versions.py --phase alpha # add -alpha suffix
113+
python scripts/sync-versions.py --phase beta # add -beta suffix
114+
python scripts/sync-versions.py --phase none # clear phase (stable)
115+
```
116+
117+
### Demote version
118+
119+
```bash
120+
python scripts/sync-versions.py --demote patch # 0.3.1 -> 0.3.0
121+
```
122+
123+
### Dry run
124+
125+
```bash
126+
python scripts/sync-versions.py --bump minor --dry-run
127+
```
128+
129+
Shows what would change without modifying any files.
130+
131+
### Git hook mode
132+
133+
```bash
134+
python scripts/sync-versions.py --auto
135+
```
136+
137+
Called by the pre-commit hook. Quiet mode, stages modified files, uses today's date.
138+
139+
## PEP 440 Mapping
140+
141+
The `get_pip_version()` function in `_version.py` converts to PEP 440 for PyPI:
142+
143+
| Our format | PEP 440 | Notes |
144+
|------------|---------|-------|
145+
| `0.3.0` | `0.3.0` | Stable release |
146+
| `0.3.0-alpha` | `0.3.0a0` | Alpha pre-release |
147+
| `0.3.0-beta` | `0.3.0b0` | Beta pre-release |
148+
| `0.3.0-rc1` | `0.3.0rc1` | Release candidate |
149+
| `0.3.0` (on dev branch) | `0.3.0.dev5` | Dev build |
150+
151+
## CHANGELOG Management
152+
153+
`sync-versions.py` manages the compare links at the bottom of `CHANGELOG.md`:
154+
155+
```markdown
156+
[Unreleased]: https://github.com/Org/repo/compare/v0.3.0...HEAD
157+
[0.3.0]: https://github.com/Org/repo/compare/v0.2.0...v0.3.0
158+
[0.2.0]: https://github.com/Org/repo/releases/tag/v0.2.0
159+
```
160+
161+
- `[Unreleased]` always points from the current tag to `HEAD`
162+
- Each version link compares from the previous tag
163+
- The first release uses `releases/tag/` format (no prior tag to compare)
164+
165+
The script updates these links automatically. It does **not** modify section headers or content -- you write changelog entries manually.
166+
167+
## Git Hooks Integration
168+
169+
### pre-commit
170+
171+
Runs `sync-versions.py --auto` to update `__version__` with the pending commit's metadata. Also:
172+
- Blocks private files from public branches
173+
- Blocks files > 10MB
174+
175+
### post-commit
176+
177+
Runs `sync-versions.py --auto` again to update the commit hash (which isn't known until after the commit).
178+
179+
### pre-push
180+
181+
Does **not** run sync-versions. Instead:
182+
- Validates Python syntax
183+
- Runs pytest
184+
- Checks for debug statements
185+
186+
## Flags Reference
187+
188+
| Flag | Description |
189+
|------|-------------|
190+
| `--check` | Verify sync status, exit 1 if out of sync |
191+
| `--bump PART` | Bump major, minor, or patch before syncing |
192+
| `--demote PART` | Demote major, minor, or patch |
193+
| `--set X.Y.Z` | Set version directly |
194+
| `--phase PHASE` | Set phase (alpha, beta, rc1, none) |
195+
| `--pre-num N` | Set PRE_RELEASE_NUM explicitly |
196+
| `--dry-run` | Show changes without modifying files |
197+
| `--auto` | Git hook mode (quiet, stages files) |
198+
| `--no-git-ver` | Skip `__version__` string update |
199+
| `--force`, `-f` | Skip confirmation prompts |
200+
| `--verbose`, `-v` | Show detailed output |

0 commit comments

Comments
 (0)