admin/basicmachines-co-basic-memory
1
0
Fork 0
mirror of https://github.com/basicmachines-co/basic-memory synced 2026-06-21 13:47:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add automated release management system

Browse Source 
- Add version management in __init__.py
- Add justfile targets for release and beta automation
- Create Claude command documentation for /release and /beta
- Implement comprehensive quality checks and validation
- Support automated version updates and git tagging

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
phernandez
2025-06-11 17:06:23 -05:00
parent 9590b934cf
commit e4b32d7bc9
4 changed files with 223 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/commands/release/beta.md
+65 -39
View File
@@ -1,69 +1,95 @@
# /beta - Create Beta Release
Create a new beta release for the current version with automated quality checks and tagging.
Create a new beta release using the automated justfile target with quality checks and tagging.
## Usage
```
/beta [version]
/beta <version>
```
**Parameters:**
- `version` (optional): Beta version like `v0.13.0b4`. If not provided, auto-increments from latest beta tag.
- `version` (required): Beta version like `v0.13.2b1` or `v0.13.2rc1`
## Implementation
You are an expert release manager for the Basic Memory project. When the user runs `/beta`, execute the following steps:
### Step 1: Pre-flight Checks
1. Check current git status for uncommitted changes
2. Verify we're on the `main` branch
3. Get the latest beta tag to determine next version if not provided
### Step 1: Pre-flight Validation
1. Verify version format matches `v\d+\.\d+\.\d+(b\d+|rc\d+)` pattern
2. Check current git status for uncommitted changes
3. Verify we're on the `main` branch
4. Confirm no existing tag with this version
### Step 2: Quality Assurance
1. Run `just check` to ensure code quality
2. If any checks fail, report issues and stop
3. Run `just update-deps` to ensure latest dependencies
4. Commit any dependency updates with proper message
### Step 2: Use Justfile Automation
Execute the automated beta release process:
```bash
just beta <version>
```
### Step 3: Version Determination
If version not provided:
1. Get latest git tags with `git tag -l "v*b*" --sort=-version:refname | head -1`
2. Auto-increment beta number (e.g., `v0.13.0b2` → `v0.13.0b3`)
3. Confirm version with user before proceeding
The justfile target handles:
- ✅ Beta version format validation (supports b1, b2, rc1, etc.)
- ✅ Git status and branch checks
- ✅ Quality checks (`just check` - lint, format, type-check, tests)
- ✅ Version update in `src/basic_memory/__init__.py`
- ✅ Automatic commit with proper message
- ✅ Tag creation and pushing to GitHub
- ✅ Beta release workflow trigger
### Step 4: Release Creation
1. Commit any remaining changes
2. Push to main: `git push origin main`
3. Create tag: `git tag {version}`
4. Push tag: `git push origin {version}`
### Step 5: Monitor Release
### Step 3: Monitor Beta Release
1. Check GitHub Actions workflow starts successfully
2. Provide installation instructions for beta
3. Report status and next steps
2. Monitor workflow at: https://github.com/basicmachines-co/basic-memory/actions
3. Verify PyPI pre-release publication
4. Test beta installation: `uv tool install basic-memory --pre`
### Step 4: Beta Testing Instructions
Provide users with beta testing instructions:
```bash
# Install/upgrade to beta
uv tool install basic-memory --pre
# Or upgrade existing installation
uv tool upgrade basic-memory --prerelease=allow
```
## Version Guidelines
- **First beta**: `v0.13.2b1`
- **Subsequent betas**: `v0.13.2b2`, `v0.13.2b3`, etc.
- **Release candidates**: `v0.13.2rc1`, `v0.13.2rc2`, etc.
- **Final release**: `v0.13.2` (use `/release` command)
## Error Handling
- If quality checks fail, provide specific fix instructions
- If git operations fail, provide manual recovery steps
- If GitHub Actions fail, provide debugging guidance
- If `just beta` fails, examine the error output for specific issues
- If quality checks fail, fix issues and retry
- If version format is invalid, correct and retry
- If tag already exists, increment version number
## Success Output
```
✅ Beta Release v0.13.0b4 Created Successfully!
✅ Beta Release v0.13.2b1 Created Successfully!
🏷️ Tag: v0.13.0b4
🏷️ Tag: v0.13.2b1
🚀 GitHub Actions: Running
📦 PyPI: Will be available in ~5 minutes
📦 PyPI: Will be available in ~5 minutes as pre-release
Install with:
uv tool upgrade basic-memory --prerelease=allow
Install/test with:
uv tool install basic-memory --pre
Monitor release: https://github.com/basicmachines-co/basic-memory/actions
```
## Beta Testing Workflow
1. **Create beta**: Use `/beta v0.13.2b1`
2. **Test features**: Install and validate new functionality
3. **Fix issues**: Address bugs found during testing
4. **Iterate**: Create `v0.13.2b2` if needed
5. **Release candidate**: Create `v0.13.2rc1` when stable
6. **Final release**: Use `/release v0.13.2` when ready
## Context
- Use the existing justfile targets (`just check`, `just update-deps`)
- Follow semantic versioning for beta releases
- Maintain release notes in CHANGELOG.md
- Use conventional commit messages
- Leverage uv-dynamic-versioning for version management
- Beta releases are pre-releases for testing new features
- Automatically published to PyPI with pre-release flag
- Uses the automated justfile target for consistency
- Version is automatically updated in `__init__.py`
- Ideal for validating changes before stable release
- Supports both beta (b1, b2) and release candidate (rc1, rc2) versions
.claude/commands/release/release.md
+35 -33
View File
@@ -1,6 +1,6 @@
# /release - Create Stable Release
Create a stable release from the current main branch with comprehensive validation.
Create a stable release using the automated justfile target with comprehensive validation.
## Usage
```
@@ -8,7 +8,7 @@ Create a stable release from the current main branch with comprehensive validati
```
**Parameters:**
- `version` (required): Release version like `v0.13.0`
- `version` (required): Release version like `v0.13.2`
## Implementation
@@ -20,53 +20,54 @@ You are an expert release manager for the Basic Memory project. When the user ru
3. Verify we're on the `main` branch
4. Confirm no existing tag with this version
### Step 2: Comprehensive Quality Checks
1. Run `just check` (lint, format, type-check, full test suite)
2. Verify test coverage meets minimum requirements (95%+)
3. Check that CHANGELOG.md contains entry for this version
4. Validate all high-priority issues are closed
### Step 2: Use Justfile Automation
Execute the automated release process:
```bash
just release <version>
```
### Step 3: Release Preparation
1. Update any version references if needed
2. Commit any final changes with message: `chore: prepare for ${version} release`
3. Push to main: `git push origin main`
The justfile target handles:
- ✅ Version format validation
- ✅ Git status and branch checks
- ✅ Quality checks (`just check` - lint, format, type-check, tests)
- ✅ Version update in `src/basic_memory/__init__.py`
- ✅ Automatic commit with proper message
- ✅ Tag creation and pushing to GitHub
- ✅ Release workflow trigger
### Step 4: Release Creation
1. Create annotated tag: `git tag -a ${version} -m "Release ${version}"`
2. Push tag: `git push origin ${version}`
3. Monitor GitHub Actions for release automation
### Step 3: Monitor Release Process
1. Check that GitHub Actions workflow starts successfully
2. Monitor workflow completion at: https://github.com/basicmachines-co/basic-memory/actions
3. Verify PyPI publication
4. Test installation: `uv tool install basic-memory`
### Step 5: Post-Release Validation
### Step 4: Post-Release Validation
1. Verify GitHub release is created automatically
2. Check PyPI publication
3. Validate release assets
4. Test installation: `uv tool install basic-memory`
### Step 6: Documentation Update
1. Update any post-release documentation
2. Create follow-up tasks if needed
4. Update any post-release documentation
## Pre-conditions Check
Before starting, verify:
- [ ] All beta testing is complete
- [ ] Critical bugs are fixed
- [ ] Breaking changes are documented
- [ ] CHANGELOG.md is updated
- [ ] CHANGELOG.md is updated (if needed)
- [ ] Version number follows semantic versioning
## Error Handling
- If any quality check fails, stop and provide fix instructions
- If changelog entry missing, prompt to create one
- If tests fail, provide debugging guidance
- If GitHub Actions fail, provide manual release steps
- If `just release` fails, examine the error output for specific issues
- If quality checks fail, fix issues and retry
- If changelog entry missing, update CHANGELOG.md and commit before retrying
- If GitHub Actions fail, check workflow logs for debugging
## Success Output
```
🎉 Stable Release v0.13.0 Created Successfully!
🎉 Stable Release v0.13.2 Created Successfully!
🏷️ Tag: v0.13.0
📋 GitHub Release: https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.0
📦 PyPI: https://pypi.org/project/basic-memory/0.13.0/
🏷️ Tag: v0.13.2
📋 GitHub Release: https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.2
📦 PyPI: https://pypi.org/project/basic-memory/0.13.2/
🚀 GitHub Actions: Completed
Install with:
@@ -79,6 +80,7 @@ uv tool upgrade basic-memory
## Context
- This creates production releases used by end users
- Must pass all quality gates before proceeding
- Follows the release workflow documented in CLAUDE.md
- Uses uv-dynamic-versioning for automatic version management
- Triggers automated GitHub release with changelog
- Uses the automated justfile target for consistency
- Version is automatically updated in `__init__.py`
- Triggers automated GitHub release with changelog
- Leverages uv-dynamic-versioning for package version management
justfile
+119
View File
@@ -58,6 +58,125 @@ check: lint format type-check test
migration message:
cd src/basic_memory/alembic && alembic revision --autogenerate -m "{{message}}"
# Create a stable release (e.g., just release v0.13.2)
release version:
#!/usr/bin/env bash
set -euo pipefail
# Validate version format
if [[ ! "{{version}}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "❌ Invalid version format. Use: v0.13.2"
exit 1
fi
# Extract version number without 'v' prefix
VERSION_NUM=$(echo "{{version}}" | sed 's/^v//')
echo "🚀 Creating stable release {{version}}"
# Pre-flight checks
echo "📋 Running pre-flight checks..."
if [[ -n $(git status --porcelain) ]]; then
echo "❌ Uncommitted changes found. Please commit or stash them first."
exit 1
fi
if [[ $(git branch --show-current) != "main" ]]; then
echo "❌ Not on main branch. Switch to main first."
exit 1
fi
# Check if tag already exists
if git tag -l "{{version}}" | grep -q "{{version}}"; then
echo "❌ Tag {{version}} already exists"
exit 1
fi
# Run quality checks
echo "🔍 Running quality checks..."
just check
# Update version in __init__.py
echo "📝 Updating version in __init__.py..."
sed -i.bak "s/__version__ = \".*\"/__version__ = \"$VERSION_NUM\"/" src/basic_memory/__init__.py
rm -f src/basic_memory/__init__.py.bak
# Commit version update
git add src/basic_memory/__init__.py
git commit -m "chore: update version to $VERSION_NUM for {{version}} release"
# Create and push tag
echo "🏷️ Creating tag {{version}}..."
git tag "{{version}}"
echo "📤 Pushing to GitHub..."
git push origin main
git push origin "{{version}}"
echo "✅ Release {{version}} created successfully!"
echo "📦 GitHub Actions will build and publish to PyPI"
echo "🔗 Monitor at: https://github.com/basicmachines-co/basic-memory/actions"
# Create a beta release (e.g., just beta v0.13.2b1)
beta version:
#!/usr/bin/env bash
set -euo pipefail
# Validate version format (allow beta/rc suffixes)
if [[ ! "{{version}}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(b[0-9]+|rc[0-9]+)$ ]]; then
echo "❌ Invalid beta version format. Use: v0.13.2b1 or v0.13.2rc1"
exit 1
fi
# Extract version number without 'v' prefix
VERSION_NUM=$(echo "{{version}}" | sed 's/^v//')
echo "🧪 Creating beta release {{version}}"
# Pre-flight checks
echo "📋 Running pre-flight checks..."
if [[ -n $(git status --porcelain) ]]; then
echo "❌ Uncommitted changes found. Please commit or stash them first."
exit 1
fi
if [[ $(git branch --show-current) != "main" ]]; then
echo "❌ Not on main branch. Switch to main first."
exit 1
fi
# Check if tag already exists
if git tag -l "{{version}}" | grep -q "{{version}}"; then
echo "❌ Tag {{version}} already exists"
exit 1
fi
# Run quality checks
echo "🔍 Running quality checks..."
just check
# Update version in __init__.py
echo "📝 Updating version in __init__.py..."
sed -i.bak "s/__version__ = \".*\"/__version__ = \"$VERSION_NUM\"/" src/basic_memory/__init__.py
rm -f src/basic_memory/__init__.py.bak
# Commit version update
git add src/basic_memory/__init__.py
git commit -m "chore: update version to $VERSION_NUM for {{version}} beta release"
# Create and push tag
echo "🏷️ Creating tag {{version}}..."
git tag "{{version}}"
echo "📤 Pushing to GitHub..."
git push origin main
git push origin "{{version}}"
echo "✅ Beta release {{version}} created successfully!"
echo "📦 GitHub Actions will build and publish to PyPI as pre-release"
echo "🔗 Monitor at: https://github.com/basicmachines-co/basic-memory/actions"
echo "📥 Install with: uv tool install basic-memory --pre"
# List all available recipes
default:
@just --list
src/basic_memory/__init__.py
+4 -1
View File
@@ -1,4 +1,7 @@
"""basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
# Package version - updated by release automation
__version__ = "0.13.1"
# API version for FastAPI - independent of package version
__version__ = "v0"
__api_version__ = "v0"