docs: add versioning and release process documentation

[ckrough]

Summary

• Add comprehensive RELEASING.md documenting version management and release procedures
• Document dual version storage in __init__.py and pyproject.toml
• Provide semantic versioning guidelines for MAJOR/MINOR/PATCH increments
• Define complete release process with git tag conventions
• Include release checklist and common version management tasks
• Update CONTRIBUTING.md and CLAUDE.md with references to release documentation

Test plan

• Verified agentspaces --version displays correct version
• Confirmed both version flags work (--version and -V)
• Documentation links added to CONTRIBUTING.md and CLAUDE.md
• Release process documented with clear step-by-step instructions

[claude]

Code Review - PR #24

Thanks for adding comprehensive release documentation! This is a valuable addition that will help maintain consistency in the release process. Here's my review:

✅ Strengths

1. Comprehensive Coverage: The RELEASING.md document thoroughly covers version management, semantic versioning guidelines, and the complete release workflow.

2. Practical Checklists: The release checklist is actionable and covers all critical steps. This will help prevent mistakes during releases.

3. Dual Version Management: Clearly documents the requirement to keep both __init__.py and pyproject.toml in sync, which is a common source of errors.

4. Good Integration: Properly integrated into existing documentation (CLAUDE.md and CONTRIBUTING.md).

5. Clean Documentation-Only Change: No code changes, minimal risk.

🔍 Observations & Suggestions

1. Version Sync Automation Opportunity

The document correctly identifies that versions must be kept in sync manually. Consider adding a simple validation script or CI check to prevent drift. This could be added to the existing CI workflow to catch mismatches early.

2. CI Integration for Version Checks

RELEASING.md mentions verifying the version command works, but this isn't automated. Consider adding a version consistency check to .github/workflows/ci.yml that verifies all three sources match (CLI output, init.py, and pyproject.toml).

3. Minor Documentation Clarifications

• Line 271-272: The Version History section says "v0.1.0 (Current)" but should include guidance on when/how to update this during releases
• Line 154: Consider adding a note about future PyPI setup requirements (API tokens, trusted publishers, etc.)
• Lines 46-50: Good note about breaking changes pre-1.0.0. Consider mentioning CHANGELOG.md as a future addition

4. Test Coverage Suggestion

The PR description mentions manually verifying --version works. Consider adding an automated test in tests/unit/cli/test_app.py to ensure the version callback continues to work correctly. This would prevent regressions.

5. Release Automation

The manual tag creation process is well documented. Worth mentioning tools like bump2version or semantic-release as future improvements?

🔒 Security

No security concerns - this is documentation only.

🎯 Minor Issues

1. Consistency: RELEASING.md uses both "future" and "Future" in notes (lines 154, 270). Minor nitpick.
2. Command Examples: All bash examples are clear and well-formatted. Good job!
3. Cross-references: Bidirectional links between docs are excellent for discoverability.

✅ Recommendation

APPROVE - This is a solid documentation PR that adds significant value. The suggestions above are enhancements for the future, not blockers.

The documentation is clear, comprehensive, and follows good practices. The manual version management is acceptable for now, but automation would be valuable as the project matures.

---

Priority of suggestions:

1. High: Add version consistency check to CI
2. Medium: Add automated test for --version flag
3. Low: Consider version sync automation script
4. Future: Release automation tooling

Great work documenting the release process! 🎉

[claude]

Pull Request Review: docs: add versioning and release process documentation

Overview

This PR adds comprehensive versioning and release automation infrastructure. The changes are well-structured and follow the project's conventions. Overall, this is a high-quality contribution that significantly improves the project's release workflow.

---

✅ Strengths

1. Excellent Documentation

• RELEASING.md is comprehensive (403 lines) with clear examples
• Good coverage of both automated and manual release processes
• Helpful troubleshooting section and common tasks reference
• Proper cross-referencing between CLAUDE.md, CONTRIBUTING.md, and RELEASING.md

2. Automated Version Validation

• scripts/check_version.py prevents version drift between init.py and pyproject.toml
• CI integration ensures versions stay synchronized
• Well-tested with unit tests covering success, mismatch, and error cases

3. Code Quality

• Follows project conventions (type hints, docstrings, ruff formatting)
• Clean separation of concerns
• Good error messages with emojis for UX
• Proper use of tomllib (Python 3.11+) for TOML parsing

4. CI/CD Improvements

• Standardized on Python 3.13 across all jobs
• Simplified test matrix (removed 3.12, keeping only 3.13)
• Added version consistency check as a required job
• Proper concurrency controls in release workflow

---

🔍 Issues & Recommendations

Critical Issues

1. Inconsistent Python Invocation in CI ⚠️

Location: .github/workflows/ci.yml:82 vs .github/workflows/release.yml:57

The version check is called differently:

• CI: uv run python scripts/check_version.py (line 82)
• Release: python scripts/check_version.py (line 57)

Recommendation: Use uv run python consistently in both places for consistency.

2. Template Directory Reference May Not Exist ⚠️

Location: pyproject.toml:142

The template_dir = "templates" configuration may cause issues if semantic-release expects CHANGELOG templates there.

Recommendations:

• Either remove this line (use semantic-release defaults)
• Or create proper CHANGELOG templates in a different directory
• Test the release workflow to ensure it doesn't fail on this

Code Quality Issues

3. Missing Explicit Encoding

Location: scripts/check_version.py:29, 44

Add explicit encoding="utf-8" to read_text() calls for consistency and safety across platforms.

4. Version Check Tests Could Be Stronger

Location: tests/unit/test_version_check.py

The tests create temporary scripts rather than testing the actual script functions directly. Consider importing and testing the actual functions for better coverage.

---

🛡️ Security Considerations

No Critical Security Issues Found ✓

• Uses GITHUB_TOKEN appropriately with minimal permissions
• No secrets exposed in code
• Proper use of tomllib (stdlib) instead of third-party TOML parsers
• Git configuration uses bot identity (good practice)

---

📊 Performance Considerations

CI Performance Impact

• Removed test matrix for Python 3.12: Reduces CI time (one less test job)
• Added version check job: Minimal overhead (~10-15 seconds)
• Net impact: Slightly faster CI overall ✓

---

🔧 Suggested Changes (Priority Order)

High Priority

1. Fix uv run python inconsistency in .github/workflows/release.yml:57
2. Verify or remove template_dir = "templates" in pyproject.toml:142
3. Add explicit encoding="utf-8" to read_text() calls

Medium Priority

4. Document first-release behavior in RELEASING.md
5. Enhance version check tests to test actual functions

Low Priority (Nice to Have)

6. Add version format validation (ensure semver compliance)
7. Consider moving RELEASING.md content to docs/ for consistency

---

📝 Summary

Recommendation: APPROVE with minor changes

This PR significantly improves the project's release infrastructure with comprehensive documentation, automated version validation, and modern semantic versioning workflow.

The issues identified are minor. The critical items (template_dir and uv run consistency) should be addressed before merge.

Code Quality: ⭐⭐⭐⭐½ (4.5/5)
Documentation: ⭐⭐⭐⭐⭐ (5/5)
Test Coverage: ⭐⭐⭐⭐ (4/5)
Security: ⭐⭐⭐⭐⭐ (5/5)

Overall: Excellent work! 🎉

[claude]

Pull Request Review

Summary

This PR adds comprehensive release automation and version management infrastructure to the project. The changes are well-structured and follow best practices. I've identified a few minor issues and suggestions for improvement.

✅ Strengths

Documentation Quality

• RELEASING.md is excellent - comprehensive, well-organized, and follows the repository's documentation standards
• Clear distinction between automated and manual release processes
• Good examples and troubleshooting guidance
• Proper integration with existing docs (CLAUDE.md, CONTRIBUTING.md)

Code Quality

• scripts/check_version.py is clean, well-documented, and follows project conventions
  • Uses Python 3.13's tomllib (stdlib) - appropriate choice
  • Proper error handling with informative messages
  • Clear exit codes
  • Explicit UTF-8 encoding for cross-platform safety

Test Coverage

• tests/unit/test_version_check.py provides comprehensive coverage (7 test cases)
• Tests both integration (subprocess) and unit (function) levels
• Good edge case coverage (missing files, invalid TOML, etc.)

CI/CD Integration

• Version consistency check integrated into CI pipeline
• Release workflow properly configured with appropriate permissions
• Good use of concurrency controls and conditional execution

🔍 Issues & Suggestions

1. BREAKING CHANGE: Python 3.13 Requirement

Severity: High

The second commit contains a breaking change that drops Python 3.12 support, but this is buried in the commit body. This should be more prominently communicated.

Recommendation:

• Consider if dropping 3.12 support is necessary at this time
• If proceeding, ensure users are clearly notified (README, release notes)
• The commit message format is correct, but the impact should be emphasized in the PR description

2. Missing Error Handling in Release Workflow

Severity: Medium

In .github/workflows/release.yml, the semantic-release commands run sequentially without explicit error checking. The default bash behavior in GitHub Actions is to exit on error, so this should work, but consider making it explicit or separating into multiple steps for clearer failure reporting.

3. Semantic Release Configuration Completeness

Severity: Low

The semantic_release.changelog.environment section in pyproject.toml (lines 148-160) contains default Jinja2 template settings that appear to be redundant.

Recommendation:

• Remove the default values unless they're being customized
• If kept, add a comment explaining why explicit defaults are needed

4. Version Check Script Path Assumption

Severity: Low

In scripts/check_version.py, the script assumes it is always in scripts/ directory. Consider using git rev-parse or making the paths configurable via CLI arguments for more robustness, though the current approach is acceptable for a project-internal script.

5. Test Fragility - Hardcoded Version Extraction

Severity: Low

In tests/unit/test_version_check.py:33-79, the test creates its own version extraction logic rather than importing the functions from the script. Lines 11-13 show that functions ARE imported for unit tests (lines 113-195), which is the right approach.

Recommendation:
Consider refactoring test_version_check_detects_mismatch to either import and use the actual check_version functions or simply test the CLI with actual files and check exit codes.

6. CHANGELOG.md Initial Content

Severity: Low

The CHANGELOG contains manual entries for Unreleased and 0.1.0. If semantic-release regenerates this file, manual entries may be lost.

Recommendation:

• Verify semantic-release preserves manual entries or merges them
• Document in RELEASING.md whether manual CHANGELOG edits are safe

7. Missing Dependencies Validation

Severity: Low

The release workflow doesn't verify that semantic-release is actually installed before running. The all-extras flag in uv sync should include it (already in pyproject.toml), so this is likely fine.

📋 Checklist Review

Based on the PR description checklist - all items completed. Suggest adding:

• Version consistency check passes locally
• CI passes (all jobs including new version-check job)

🎯 Recommendations

Before Merge:

1. Address the Python 3.13 breaking change - ensure this is intentional and well-communicated
2. Verify semantic-release CHANGELOG behavior - ensure manual entries are not lost
3. Consider simplifying release workflow - possibly separate version and publish steps

Nice to Have (Post-Merge):

1. Add a .releaserc file for semantic-release config (optional, TOML is fine)
2. Consider adding release notes template
3. Add a test that runs the actual version check script end-to-end

🔒 Security

No security concerns identified. The workflow uses appropriate permissions, GITHUB_TOKEN, and has persist-credentials explicitly set.

🎨 Code Style

All changes follow the project conventions with type hints, Google-style docstrings, ruff formatting, mypy strict checks, and UTF-8 encoding.

Final Recommendation

APPROVE with minor suggestions

This is a solid implementation of release automation. The identified issues are minor and most are optional improvements. The breaking change for Python 3.13 is the only item that needs explicit confirmation before merge.

Great work on the comprehensive documentation and test coverage! 🚀

---

Reviewed using repository guidelines from CLAUDE.md

[claude]

Pull Request Review

Thank you for this comprehensive documentation PR! This adds valuable release process documentation and automation. Overall this is well-structured and thorough. Below are my findings organized by category.

---

✅ Strengths

1. Comprehensive documentation - RELEASING.md is thorough and well-organized
2. Automation - semantic-release integration will streamline releases
3. Version consistency - CI check prevents version drift (great defensive measure)
4. Clear conventions - Conventional commits are well-documented
5. Python 3.13 alignment - Consistent upgrade across all files

---

🔴 Critical Issues

1. Release Workflow Permissions Issue

Location: .github/workflows/release.yml:14-16

permissions:
  contents: write
  issues: write
  pull-requests: write

Problem: Missing id-token: write permission if you plan to publish to PyPI with trusted publishing. Also, semantic-release may need additional permissions.

Recommendation:

permissions:
  contents: write
  issues: write
  pull-requests: write
  id-token: write  # For PyPI trusted publishing

2. Git Configuration Uses Bot Account Without Clear Token Strategy

Location: .github/workflows/release.yml:44-46

The workflow uses github-actions[bot] but relies on GITHUB_TOKEN. This should work, but the documentation doesn't clarify token requirements.

Recommendation: Add a note in RELEASING.md about token permissions and why default GITHUB_TOKEN is sufficient (or if a PAT is needed for triggering subsequent workflows).

3. Version Consistency Check Runs After Publish

Location: .github/workflows/release.yml:55-57

- name: Verify version consistency
  if: success()
  run: uv run python scripts/check_version.py

Problem: If version check fails AFTER publishing, you've already created the release. This should run BEFORE publishing.

Fix:

- name: Verify version consistency
  run: uv run python scripts/check_version.py

- name: Run semantic-release
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    uv run semantic-release version --print
    uv run semantic-release publish

---

⚠️ High Priority Issues

4. Semantic Release Configuration May Not Update Both Files

Location: pyproject.toml:129-131

[tool.semantic_release]
version_toml = ["pyproject.toml:project.version"]
version_variables = ["src/agentspaces/__init__.py:__version__"]

Concern: Need to verify semantic-release updates both locations atomically. If one fails, you'll have version drift.

Recommendation: Add integration test or manual verification step to confirm both files are updated in the same commit by semantic-release.

5. Python 3.12 Still in Test Coverage Check

Location: .github/workflows/ci.yml:78

Although you removed the matrix, this comment suggests 3.12 was recently supported. The project now requires 3.13+ which is quite recent (released October 2024).

Recommendation: Consider whether dropping 3.12 support is intentional or if the matrix should be restored for broader compatibility. Python 3.13 is very new and many users may not have it yet.

6. Major Version Bump Behavior Not Tested

Location: RELEASING.md:91-97

Documentation says to use ! or BREAKING CHANGE: for major bumps, but there's no example of testing this. Given the major_on_zero = true setting, a breaking change while at 0.x.y will bump to 1.0.0.

Recommendation: Add a section in RELEASING.md about testing the release process in a fork or branch first, especially for major version bumps.

---

📝 Medium Priority Issues

7. CHANGELOG.md Contains Incorrect Date

Location: CHANGELOG.md:18

## [0.1.0] - 2024-12-22

Problem: Today's date is 2025-12-22, not 2024-12-22.

Fix: Update to 2025-12-22 or use the actual release date from git tags.

8. Redundant Version Check in Release Workflow

Location: .github/workflows/release.yml

The CI workflow already has a version-check job that runs on all PRs. Running it again in release workflow is redundant since all changes must pass CI before merging to main.

Recommendation: Remove the post-publish version check or clarify why it's needed (perhaps to verify semantic-release worked correctly).

9. Missing Error Handling in check_version.py

Location: scripts/check_version.py:44

content = pyproject_file.read_text(encoding="utf-8")
data = tomllib.loads(content)

Issue: If pyproject.toml is malformed, the error message won't be helpful.

Recommendation:

try:
    content = pyproject_file.read_text(encoding="utf-8")
    data = tomllib.loads(content)
    return data.get("project", {}).get("version")
except tomllib.TOMLDecodeError as e:
    print(f"❌ Error: Invalid TOML in {pyproject_file}: {e}", file=sys.stderr)
    return None
except KeyError:
    return None

10. Inconsistent Terminology: "Bump" vs "Increment"

Location: RELEASING.md

The document alternates between "version bump" and "version increment". Pick one for consistency.

Recommendation: Use "version bump" consistently (matches industry standard terminology).

---

💡 Low Priority / Style Issues

11. Overly Detailed Manual Release Process

Location: RELEASING.md:149-261

The manual release section is very detailed (113 lines) despite being discouraged. This might encourage manual releases when automation should be preferred.

Recommendation: Move detailed manual steps to a separate "Manual Release" section at the end or collapse them, emphasizing "Use automated releases unless absolutely necessary."

12. Missing Rollback Instructions

Location: RELEASING.md

No documentation on how to rollback a bad release (delete tag, revert commits, etc.).

Recommendation: Add a "Rollback" section with steps to undo a release.

13. No CI Status Badge in README

Location: README.md

With the enhanced CI including version checks, consider adding status badges.

Recommendation:

[![CI](https://github.com/ckrough/agentspaces/workflows/CI/badge.svg)](https://github.com/ckrough/agentspaces/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/ckrough/agentspaces/branch/main/graph/badge.svg)](https://codecov.io/gh/ckrough/agentspaces)

14. Semantic Release --print Flag May Not Be Necessary

Location: .github/workflows/release.yml:52

uv run semantic-release version --print
uv run semantic-release publish

Running version --print separately might be for debugging, but publish should handle everything.

Recommendation: Either document why this is split or combine into single semantic-release publish command.

---

🔒 Security Considerations

15. No Secrets Scanning Mentioned

While not directly related to this PR, the release process would benefit from ensuring no secrets are committed before releasing.

Recommendation: Consider adding git-secrets or similar to pre-commit hooks mentioned in CONTRIBUTING.md.

---

🧪 Test Coverage

16. No Tests for check_version.py Script

Location: scripts/check_version.py

This is a critical script that runs in CI, but there are no unit tests for it.

Recommendation: Add tests/unit/test_check_version.py with test cases:

• Versions match
• Versions mismatch
• Missing files
• Malformed TOML
• Missing version fields

---

📊 Performance Considerations

No significant performance concerns. The version check script is fast and runs only on CI.

---

📚 Documentation Quality

Overall documentation quality is excellent. The RELEASING.md is comprehensive and well-organized. Minor suggestions:

1. Add a table of contents to RELEASING.md (it's quite long)
2. Consider adding visual diagrams for the automated release flow
3. Link to python-semantic-release docs for advanced configuration

---

✅ Positives Worth Highlighting

1. Excellent defensive programming - The version consistency check prevents a whole class of bugs
2. Clear documentation structure - Well-organized with good examples
3. Conventional commits adoption - Industry best practice
4. Comprehensive coverage - Addresses both automated and manual scenarios
5. Python 3.13 upgrade - Staying current with Python releases

---

🎯 Summary

Recommendation: Approve with minor changes

This is a solid PR that adds important infrastructure. The critical issues are relatively minor and mostly involve reordering steps in the release workflow. The documentation is comprehensive and valuable.

Must-Fix Before Merge:

1. Move version consistency check before publish in release.yml (Add GitHub Actions CI/CD workflow #3)
2. Fix CHANGELOG date (feat: add workspace state management commands (#7) #7)
3. Verify semantic-release updates both version files (feat: add workspace metadata persistence and skill generation #4)

Should Consider:

4. Add tests for check_version.py (fix: add .agentspace/ to git exclude to allow workspace deletion #16)
5. Add rollback documentation (refactor: rename project from AgentSpaces to agentspaces #12)
6. Clarify token strategy (Increment 2: Python environment management with uv #2)

Nice to Have:

7. Add CI badges to README (refactor: replace 'as' alias with 'agentspaces' in docs and output #13)
8. Add TOC to RELEASING.md
9. Consider restoring Python 3.12 support for broader compatibility (feat: add agent launching with Claude Code support #5)

---

Great work on this PR! The automated release process will be a significant improvement to the project's maintainability.

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

[claude]

Pull Request Review: Release Process Documentation

Summary

This PR adds comprehensive release process documentation and automated versioning via python-semantic-release. The implementation is well-structured and follows best practices.

Strengths

• Excellent RELEASING.md documentation covering both automated and manual releases
• Clean implementation of scripts/check_version.py with proper error handling
• Strong test coverage (191 lines) with good edge case coverage
• Type safety with proper type hints
• CI job added to prevent version drift

Critical Issues

1. Release Workflow Configuration Issue (.github/workflows/release.yml:52-53)

Running 'version --print' before 'publish' may cause problems. The --print flag is a dry-run. Recommend using just 'semantic-release publish' which handles both versioning and publishing.

2. CHANGELOG Date Error

CHANGELOG.md:18 shows 2024-12-22 but should be 2025-12-22.

Recommendations

Security

Release workflow grants broad permissions (contents, issues, pull-requests write). Consider reducing to just contents:write unless semantic-release needs the others.

Code Organization

tests/unit/test_version_check.py uses sys.path manipulation which is fragile. Consider moving scripts/check_version.py to src/agentspaces/ as a proper module.

Python Version Support

pyproject.toml now requires Python >=3.13 only. Is dropping 3.12 support intentional? Most packages support a range during transitions.

Test Matrix

CI workflow removed Python version matrix testing. Fine if only supporting 3.13, but document this decision.

Minor Improvements

• Add GitHub URL to error messages for users without local checkout
• Update hardcoded 2024 dates in RELEASING.md to 2025
• Consider grouping unit tests by function using test classes

Security Review

No security concerns identified. Script only reads files, no injection vulnerabilities, proper subprocess usage, official GitHub Actions.

Test Coverage

Excellent coverage of version validation, unit tests, edge cases (missing files, invalid TOML, mismatches).

Overall Assessment

Recommendation: Approve with minor fixes

High-quality work that significantly improves the release process.

Priority fixes:

1. Fix semantic-release command sequence
2. Update CHANGELOG date
3. Consider reducing workflow permissions

Great work on the comprehensive documentation and automation!