Skip to content

Commit 97ed3d0

Browse files
henrygarnerhenrygarner
committed
Add versioning policy, CLAUDE.md and version bump script
1 parent 6b686b4 commit 97ed3d0

4 files changed

Lines changed: 187 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ When modifying code or tests:
6565

6666
* **Allium language semantics and syntax:** https://juxt.github.io/allium/language (authoritative for any language-level behaviour in this repository)
6767
* **Architecture & key concepts:** `README.md` and `docs/project/architecture.md`.
68+
* **Versioning policy:** `VERSIONING.md` — defines which packages share versions and how to bump them.
6869

6970
---
7071

‎CLAUDE.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Allium tools
2+
3+
This is a monorepo for Allium language tooling: parsers, CLI tools, an LSP server, a tree-sitter grammar, and editor plugins for VS Code, Neovim and Emacs.
4+
5+
Read `README.md` for an overview of the project and `AGENTS.md` for development guidance.
6+
7+
## Key policies
8+
9+
- **Versioning:** See `VERSIONING.md` for the tiered versioning scheme and how to bump versions.
10+
- **Specs:** After completing any feature work, update the Allium specs in `docs/project/specs/` to reflect current behaviour.

‎VERSIONING.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Versioning policy
2+
3+
The Allium language is at version 1. Tooling versions should align with the language where appropriate.
4+
5+
## Version tiers
6+
7+
### Core tier: major.minor tracks the language
8+
9+
These packages share a major.minor version that tracks the Allium language version. Patch versions may differ between packages (e.g. a parser bugfix doesn't force a CLI release).
10+
11+
| Package | Manifest | Version source |
12+
|---|---|---|
13+
| allium-parser | `crates/allium-parser/Cargo.toml` | Cargo workspace (`Cargo.toml`) |
14+
| allium (Rust CLI) | `crates/allium/Cargo.toml` | Cargo workspace (`Cargo.toml`) |
15+
| allium-cli (Node) | `packages/allium-cli/package.json` | Hardcoded |
16+
| allium-lsp | `packages/allium-lsp/package.json` | Hardcoded |
17+
| tree-sitter-allium | `packages/tree-sitter-allium/package.json` | Hardcoded |
18+
19+
The canonical major.minor lives in two places:
20+
21+
- `Cargo.toml` workspace version (Rust crates)
22+
- `package.json` root version (npm packages)
23+
24+
These two must always agree on major.minor.
25+
26+
### Editor tier: versions independently
27+
28+
Editor plugins are thin integration layers that delegate to the LSP and tree-sitter. They version at their own pace, reflecting their own maturity and feature set.
29+
30+
| Package | Manifest |
31+
|---|---|
32+
| allium-vscode | `extensions/allium/package.json` |
33+
| allium-mode | `packages/allium-mode/allium-mode.el` and `allium-mode-pkg.el` |
34+
| nvim-allium | No version declared (distributed via plugin managers) |
35+
36+
Editor plugins should document which core version they're compatible with in their README.
37+
38+
## Bumping versions
39+
40+
Use `scripts/version-bump.sh` to update core-tier versions:
41+
42+
```bash
43+
# Set all core-tier packages to 1.0.0
44+
./scripts/version-bump.sh 1.0.0
45+
46+
# Dry run — show what would change without writing
47+
./scripts/version-bump.sh --dry-run 1.0.0
48+
```
49+
50+
Editor-tier packages are bumped manually as needed.
51+
52+
## Rules
53+
54+
1. A grammar or language-level change bumps the core-tier minor (or major) version.
55+
2. A bugfix in a single core package bumps only that package's patch version.
56+
3. Editor plugins declare their own versions and note compatible core versions.
57+
4. The two canonical version sources (Cargo workspace, root package.json) must always share the same major.minor.

‎scripts/version-bump.sh‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
# Bump core-tier package versions across the monorepo.
5+
# See VERSIONING.md for the versioning policy.
6+
#
7+
# Usage:
8+
# ./scripts/version-bump.sh [--dry-run] <version>
9+
#
10+
# Examples:
11+
# ./scripts/version-bump.sh 1.0.0
12+
# ./scripts/version-bump.sh --dry-run 1.0.0
13+
14+
DRY_RUN=false
15+
VERSION=""
16+
17+
for arg in "$@"; do
18+
case "$arg" in
19+
--dry-run) DRY_RUN=true ;;
20+
-*) echo "Unknown flag: $arg" >&2; exit 1 ;;
21+
*) VERSION="$arg" ;;
22+
esac
23+
done
24+
25+
if [[ -z "$VERSION" ]]; then
26+
echo "Usage: version-bump.sh [--dry-run] <version>" >&2
27+
exit 1
28+
fi
29+
30+
if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
31+
echo "Error: version must be in semver format (e.g. 1.0.0)" >&2
32+
exit 1
33+
fi
34+
35+
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
36+
37+
# Files to update and the sed pattern for each.
38+
# Format: file:pattern
39+
TARGETS=(
40+
# Cargo workspace (covers allium-parser and allium via workspace inheritance)
41+
"Cargo.toml:s/^version = \"[0-9]*\.[0-9]*\.[0-9]*\"/version = \"$VERSION\"/"
42+
43+
# Root package.json
44+
"package.json"
45+
46+
# Core-tier npm packages
47+
"packages/allium-cli/package.json"
48+
"packages/allium-lsp/package.json"
49+
"packages/tree-sitter-allium/package.json"
50+
)
51+
52+
update_json_version() {
53+
local file="$1"
54+
local full_path="$ROOT/$file"
55+
56+
if [[ ! -f "$full_path" ]]; then
57+
echo " SKIP $file (not found)"
58+
return
59+
fi
60+
61+
local current
62+
current=$(grep -m1 '"version"' "$full_path" | sed 's/.*"version": *"\([^"]*\)".*/\1/')
63+
64+
if [[ "$current" == "$VERSION" ]]; then
65+
echo " OK $file (already $VERSION)"
66+
return
67+
fi
68+
69+
if $DRY_RUN; then
70+
echo " WOULD $file: $current -> $VERSION"
71+
else
72+
sed -i '' "s/\"version\": *\"$current\"/\"version\": \"$VERSION\"/" "$full_path"
73+
echo " SET $file: $current -> $VERSION"
74+
fi
75+
}
76+
77+
update_cargo_version() {
78+
local file="$1"
79+
local full_path="$ROOT/$file"
80+
81+
if [[ ! -f "$full_path" ]]; then
82+
echo " SKIP $file (not found)"
83+
return
84+
fi
85+
86+
local current
87+
current=$(grep -m1 '^version' "$full_path" | sed 's/.*"\([^"]*\)".*/\1/')
88+
89+
if [[ "$current" == "$VERSION" ]]; then
90+
echo " OK $file (already $VERSION)"
91+
return
92+
fi
93+
94+
if $DRY_RUN; then
95+
echo " WOULD $file: $current -> $VERSION"
96+
else
97+
sed -i '' "s/^version = \"$current\"/version = \"$VERSION\"/" "$full_path"
98+
echo " SET $file: $current -> $VERSION"
99+
fi
100+
}
101+
102+
echo "Core-tier version bump -> $VERSION"
103+
if $DRY_RUN; then
104+
echo "(dry run — no files will be modified)"
105+
fi
106+
echo ""
107+
108+
# Cargo workspace
109+
update_cargo_version "Cargo.toml"
110+
111+
# npm packages
112+
update_json_version "package.json"
113+
update_json_version "packages/allium-cli/package.json"
114+
update_json_version "packages/allium-lsp/package.json"
115+
update_json_version "packages/tree-sitter-allium/package.json"
116+
117+
echo ""
118+
echo "Done. Editor-tier packages (allium-vscode, allium-mode, nvim-allium) are not touched."
119+
echo "Bump those manually if needed."

0 commit comments

Comments
 (0)