fix: harden tag_release and add release docs

acgetchell · acgetchell · commit 9ed8915e9927 · 2026-03-07T09:28:47.000-08:00
Fix three bugs in tag_release.py:
- _github_anchor now matches github-slugger (strips brackets, removes
  non-alphanumeric punctuation, replaces whitespace with hyphens)
- Tag deletion deferred until after changelog extraction succeeds,
  preventing orphaned tag loss on validation failure
- Force push instruction emitted when --force flag is used

Add docs/RELEASING.md with step-by-step release workflow (version
bump, changelog generation, benchmarks, tagging, crates.io publish).

Add CHANGELOG.md reference to README.md design goals section.
diff --git a/README.md b/README.md
@@ -36,6 +36,8 @@ while keeping the API intentionally small and explicit.
 - ✅ Stack storage only (no heap allocation in core types)
 - ✅ `unsafe` forbidden
 
+See [CHANGELOG.md](CHANGELOG.md) for details.
+
 ## 🚫 Anti-goals
 
 - Bare-metal performance: see [`blas-src`](https://crates.io/crates/blas-src), [`lapack-src`](https://crates.io/crates/lapack-src), [`openblas-src`](https://crates.io/crates/openblas-src)
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
@@ -0,0 +1,214 @@
+# Releasing la-stack
+
+This guide documents the exact commands for performing a clean release using a
+dedicated release PR, followed by tagging, publishing to crates.io, and
+creating a GitHub release.
+
+Applies to versions vX.Y.Z. Prefer updating documentation before publishing
+to crates.io.
+
+---
+
+## Conventions and environment
+
+Set these variables to avoid repeating the version string:
+
+```bash
+# tag has the leading v, version does not
+TAG=vX.Y.Z
+VERSION=${TAG#v}
+```
+
+Verify your git remotes:
+
+```bash
+git remote -v
+```
+
+Ensure your local main is up to date before beginning:
+
+```bash
+git checkout main
+git pull --ff-only
+```
+
+---
+
+## Step 1: Create a clean release PR
+
+This PR should primarily include: version bumps, changelog updates, and
+documentation updates. All major code changes should already be on main.
+
+**Exception:** Small, critical fixes discovered during the release process
+(e.g., documentation errors, script bugs, formatting issues) may be included
+but should be minimal and release-critical only.
+
+1. Create the release branch
+
+```bash
+git checkout -b release/$TAG
+```
+
+2. Bump versions
+
+Preferred (if cargo-edit is installed):
+
+```bash
+# Bump package version in Cargo.toml
+cargo set-version $VERSION
+```
+
+Alternative: edit `Cargo.toml` manually (update `version = "..."` under
+`[package]`).
+
+Update references in documentation (search, then manually edit as needed):
+
+```bash
+# List occurrences of version-like strings to review
+rg -n "\bv?[0-9]+\.[0-9]+\.[0-9]+\b" README.md docs/ || true
+```
+
+3. Generate changelog using a temporary local tag (DO NOT PUSH this tag)
+
+```bash
+# Create a temporary annotated tag locally to enable changelog generation
+# Do not push this tag; it will be recreated later after merge
+git tag -a "$TAG" -m "la-stack $TAG"
+
+# Generate changelog (git-cliff + post-processing)
+just changelog
+```
+
+4. Run benchmarks and update the README comparison table
+
+```bash
+# Run vs_linalg benchmarks (la-stack vs nalgebra vs faer) and update the
+# README benchmark table + SVG plot
+just bench-vs-linalg
+just plot-vs-linalg-readme
+```
+
+Review the updated table in `README.md` and the plot in `docs/assets/` for
+accuracy.
+
+5. Stage and commit release artifacts
+
+```bash
+git add Cargo.toml Cargo.lock CHANGELOG.md README.md docs/
+
+git commit -m "chore(release): release $TAG
+
+- Bump version to $TAG
+- Update changelog with latest changes
+- Update benchmark comparison table
+- Update documentation for release"
+```
+
+6. Push the branch and open a PR
+
+```bash
+git push -u origin "release/$TAG"
+```
+
+PR metadata:
+
+- Title: chore(release): release $TAG
+- Description: Clean release PR with version bump, changelog, and
+  documentation updates. No code changes.
+
+Note: Do NOT push the temporary tag created in step 3.
+
+### Handling fixes discovered during release process
+
+If you discover issues (bugs, formatting problems, etc.) after creating the
+changelog:
+
+1. **For critical fixes that must be in this release:**
+
+   ```bash
+   # Make your fixes
+   # Run code quality tools
+   # Commit the fixes
+   git add .
+   git commit -m "fix: [description of fix]"
+
+   # Delete the temporary tag and regenerate changelog
+   git tag -d "$TAG"
+   git tag -a "$TAG" -m "la-stack $TAG"
+   just changelog
+
+   # Commit updated changelog
+   git add CHANGELOG.md
+   git commit -m "docs: update changelog with release fixes"
+   ```
+
+2. **For non-critical fixes:**
+   - Document them as known issues in the release notes
+   - Include them in the next release
+   - This avoids the changelog regeneration loop
+
+---
+
+## Step 2: After the PR is merged into main
+
+1. Sync your local main to the merge commit
+
+```bash
+git checkout main
+git pull --ff-only
+```
+
+2. Recreate the final annotated tag using the changelog content
+
+```bash
+# Remove the temporary local tag if it exists
+git tag -d "$TAG" 2>/dev/null || true
+
+# Create the final annotated tag with the changelog section as the tag message
+# Note: For large changelogs (>125KB), this automatically creates an annotated
+# tag with a reference message pointing to CHANGELOG.md instead of the full
+# content
+just tag "$TAG"
+```
+
+3. (Optional) Verify tag message content
+
+```bash
+git tag -l --format='%(contents)' "$TAG"
+```
+
+4. Push the tag
+
+```bash
+git push origin "$TAG"
+```
+
+5. Create the GitHub release with notes from the tag annotation
+
+```bash
+# Requires GitHub CLI (gh) and authenticated session
+gh release create "$TAG" --notes-from-tag
+```
+
+6. Publish to crates.io
+
+```bash
+# Sanity check before publishing
+cargo publish --dry-run
+
+# Publish the crate (ensure docs are already updated on main via the PR)
+cargo publish
+```
+
+---
+
+## Notes and tips
+
+- Never push the temporary tag created for changelog generation; only push
+  the final tag after the PR is merged.
+- Keep the release PR strictly to version + changelog + documentation to
+  maintain a clean history.
+- If multiple crates or files reference the version, confirm all of them are
+  updated consistently.
+- For future convenience, parts of this document can be automated into a
+  release script.
diff --git a/scripts/tag_release.py b/scripts/tag_release.py
@@ -163,15 +163,23 @@ def _get_repo_url() -> str:
 
 
 def _github_anchor(changelog: Path, version: str) -> str:
-    """Build a GitHub-compatible anchor for the version heading."""
+    """Build a GitHub-compatible heading anchor (matches ``github-slugger``)."""
     try:
         for line in changelog.read_text(encoding="utf-8").splitlines():
             if line.startswith("## ") and (f"v{version}" in line or f"[{version}]" in line):
-                heading = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", line)
-                return heading[2:].strip().lower().replace(" ", "-").replace(".", "")
+                heading = line.removeprefix("## ").strip()
+                # Strip inline-link markup [text](url) → text
+                heading = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", heading)
+                # Strip reference-style brackets [text] → text
+                heading = re.sub(r"\[([^\]]+)\]", r"\1", heading)
+                heading = heading.lower()
+                # Remove everything except letters, digits, spaces, hyphens
+                heading = re.sub(r"[^a-z0-9\s-]", "", heading)
+                # Replace whitespace runs with a single hyphen
+                return re.sub(r"\s+", "-", heading)
     except OSError:
         pass
-    return f"v{version.replace('.', '')}"
+    return re.sub(r"[^a-z0-9-]", "", f"v{version}".lower())
 
 
 # ---------------------------------------------------------------------------
@@ -188,16 +196,14 @@ def create_tag(tag_version: str, *, force: bool = False) -> None:
     validate_semver(tag_version)
     version = parse_version(tag_version)
 
-    # Handle existing tag
-    if _tag_exists(tag_version):
-        if not force:
-            print(f"{_YELLOW}Tag '{tag_version}' already exists.{_RESET}", file=sys.stderr)
-            print(f"Use --force to recreate, or delete manually: git tag -d {tag_version}", file=sys.stderr)
-            sys.exit(1)
-        print(f"{_BLUE}Deleting existing tag '{tag_version}'...{_RESET}")
-        _delete_tag(tag_version)
+    # Check for existing tag (but don't delete yet — validate first)
+    tag_existed = _tag_exists(tag_version)
+    if tag_existed and not force:
+        print(f"{_YELLOW}Tag '{tag_version}' already exists.{_RESET}", file=sys.stderr)
+        print(f"Use --force to recreate, or delete manually: git tag -d {tag_version}", file=sys.stderr)
+        sys.exit(1)
 
-    # Extract changelog section
+    # Extract changelog section (before any mutation)
     changelog = find_changelog()
     section = extract_changelog_section(changelog, version)
     section_bytes = len(section.encode("utf-8"))
@@ -226,6 +232,11 @@ def create_tag(tag_version: str, *, force: bool = False) -> None:
             print("... (truncated for preview)")
         print("----------------------------------------")
 
+    # Delete existing tag only after all validation succeeds
+    if tag_existed and force:
+        print(f"{_BLUE}Deleting existing tag '{tag_version}'...{_RESET}")
+        _delete_tag(tag_version)
+
     # Create annotated tag
     label = "reference" if is_truncated else "full changelog"
     print(f"{_BLUE}Creating annotated tag '{tag_version}' with {label} content...{_RESET}")
@@ -235,7 +246,10 @@ def create_tag(tag_version: str, *, force: bool = False) -> None:
     print(f"{_GREEN}✓ Successfully created tag '{tag_version}'{_RESET}")
     print()
     print("Next steps:")
-    print(f"  1. Push the tag: {_BLUE}git push origin {tag_version}{_RESET}")
+    if force:
+        print(f"  1. Force-push the tag: {_BLUE}git push --force origin {tag_version}{_RESET}")
+    else:
+        print(f"  1. Push the tag: {_BLUE}git push origin {tag_version}{_RESET}")
     print(f"  2. Create GitHub release: {_BLUE}gh release create {tag_version} --notes-from-tag{_RESET}")
     if is_truncated:
         print(f"\n{_YELLOW}Note: Tag annotation references CHANGELOG.md due to size (>125KB).{_RESET}")
diff --git a/scripts/tests/test_tag_release.py b/scripts/tests/test_tag_release.py
@@ -10,6 +10,7 @@
 import tag_release
 from tag_release import (
     _GITHUB_TAG_ANNOTATION_LIMIT,
+    _github_anchor,
     extract_changelog_section,
     find_changelog,
     parse_version,
@@ -144,6 +145,37 @@ def test_raises_for_empty_section(self, tmp_path: Path) -> None:
             extract_changelog_section(changelog, "1.0.0")
 
 
+# ---------------------------------------------------------------------------
+# GitHub anchor generation
+# ---------------------------------------------------------------------------
+
+
+class TestGitHubAnchor:
+    """Verify _github_anchor matches github-slugger output."""
+
+    def test_bracketed_heading(self, tmp_path: Path) -> None:
+        """Heading ``## [1.0.0] - 2025-01-01`` should strip brackets and dots."""
+        changelog = tmp_path / "CHANGELOG.md"
+        changelog.write_text(
+            "# Changelog\n\n## [1.0.0] - 2025-01-01\n\n- Item\n",
+            encoding="utf-8",
+        )
+        assert _github_anchor(changelog, "1.0.0") == "100---2025-01-01"
+
+    def test_plain_v_heading(self, tmp_path: Path) -> None:
+        changelog = tmp_path / "CHANGELOG.md"
+        changelog.write_text(
+            "# Changelog\n\n## v0.2.0\n\n- Item\n",
+            encoding="utf-8",
+        )
+        assert _github_anchor(changelog, "0.2.0") == "v020"
+
+    def test_fallback_when_not_found(self, tmp_path: Path) -> None:
+        changelog = tmp_path / "CHANGELOG.md"
+        changelog.write_text("# Changelog\n", encoding="utf-8")
+        assert _github_anchor(changelog, "9.9.9") == "v999"
+
+
 # ---------------------------------------------------------------------------
 # Tag size limit handling
 # ---------------------------------------------------------------------------
@@ -258,3 +290,25 @@ def test_force_recreates_tag(
 
         mock_delete.assert_called_once_with("v1.0.0")
         mock_git_input.assert_called_once()
+
+    @patch("tag_release._tag_exists", return_value=True)
+    @patch("tag_release.find_changelog")
+    @patch("tag_release.extract_changelog_section", side_effect=LookupError("not found"))
+    @patch("tag_release._delete_tag")
+    def test_force_does_not_delete_tag_if_changelog_fails(
+        self,
+        mock_delete: MagicMock,
+        _mock_extract: MagicMock,
+        mock_find: MagicMock,
+        _mock_exists: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        """Tag must not be deleted if changelog extraction fails."""
+        changelog = tmp_path / "CHANGELOG.md"
+        changelog.write_text("# Changelog\n", encoding="utf-8")
+        mock_find.return_value = changelog
+
+        with pytest.raises(LookupError):
+            tag_release.create_tag("v1.0.0", force=True)
+
+        mock_delete.assert_not_called()
