feat: implement comprehensive release process and automation (issue #81)
- Add complete release automation script (release.py) with version management - Add semantic versioning validation and git integration - Create automated changelog generation from git commits - Add comprehensive Makefile targets for release workflow - Set up package building with source and wheel distributions - Add git tagging and repository management - Create extensive release documentation (RELEASE.md) - Add CHANGELOG.md with standardized format - Update dependencies in pyproject.toml (add toml package) Release commands added: - make release-status - Show current release status - make release-validate - Validate repository for release - make release-prepare VERSION=x.y.z - Prepare new release - make release-build - Build release packages - make release-publish VERSION=x.y.z - Complete release workflow - make release-dry-run VERSION=x.y.z - Test release preparation Features: - Semantic versioning with pre-release support - Automated version updates across files - Git status validation and branch checking - Test execution validation - Package building with build tool integration - Git tagging with proper annotations - Comprehensive error handling and validation Resolves #81 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
332
RELEASE.md
Normal file
332
RELEASE.md
Normal file
@@ -0,0 +1,332 @@
|
||||
# MarkiTect Release Process
|
||||
|
||||
This document describes the release process for MarkiTect, including versioning strategy, automation tools, and distribution guidelines.
|
||||
|
||||
## Quick Start
|
||||
|
||||
The simplest way to create a release:
|
||||
|
||||
```bash
|
||||
# 1. Prepare the release
|
||||
make release-prepare VERSION=1.0.0
|
||||
|
||||
# 2. Review and commit changes
|
||||
git add -A && git commit -m "Prepare release 1.0.0"
|
||||
|
||||
# 3. Publish the release
|
||||
make release-publish VERSION=1.0.0
|
||||
```
|
||||
|
||||
## Release Commands
|
||||
|
||||
### Status and Validation
|
||||
|
||||
```bash
|
||||
# Check current release status
|
||||
make release-status
|
||||
|
||||
# Validate repository for release
|
||||
make release-validate
|
||||
```
|
||||
|
||||
### Release Preparation
|
||||
|
||||
```bash
|
||||
# Prepare a new release (updates version, changelog)
|
||||
make release-prepare VERSION=x.y.z
|
||||
|
||||
# Test preparation without making changes
|
||||
make release-dry-run VERSION=x.y.z
|
||||
```
|
||||
|
||||
### Building and Publishing
|
||||
|
||||
```bash
|
||||
# Build release packages only
|
||||
make release-build [VERSION=x.y.z]
|
||||
|
||||
# Complete release (build + tag + publish)
|
||||
make release-publish VERSION=x.y.z
|
||||
```
|
||||
|
||||
## Versioning Strategy
|
||||
|
||||
MarkiTect follows [Semantic Versioning](https://semver.org/):
|
||||
|
||||
- **MAJOR.MINOR.PATCH** (e.g., 1.2.3)
|
||||
- **Pre-release**: MAJOR.MINOR.PATCH-{alpha|beta|rc}.N (e.g., 1.2.3-beta.1)
|
||||
|
||||
### Version Types
|
||||
|
||||
- **Major (X.0.0)**: Breaking changes, incompatible API changes
|
||||
- **Minor (x.Y.0)**: New features, backward compatible
|
||||
- **Patch (x.y.Z)**: Bug fixes, backward compatible
|
||||
- **Pre-release**: Alpha, beta, or release candidate versions
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Major release
|
||||
make release-prepare VERSION=2.0.0
|
||||
|
||||
# Minor release
|
||||
make release-prepare VERSION=1.1.0
|
||||
|
||||
# Patch release
|
||||
make release-prepare VERSION=1.0.1
|
||||
|
||||
# Pre-release
|
||||
make release-prepare VERSION=1.1.0-beta.1
|
||||
```
|
||||
|
||||
## Release Validation
|
||||
|
||||
Before a release can be created, the following validations are performed:
|
||||
|
||||
### Required Conditions
|
||||
|
||||
1. **Clean Repository**: No uncommitted changes
|
||||
2. **Main Branch**: Must be on the `main` branch
|
||||
3. **Passing Tests**: All tests must pass
|
||||
4. **Valid Version**: Version must follow semantic versioning
|
||||
5. **Version Increment**: New version must be greater than current
|
||||
|
||||
### Override Validation
|
||||
|
||||
Use `--force` to override validation warnings:
|
||||
|
||||
```bash
|
||||
python release.py prepare --version 1.0.1 --force
|
||||
```
|
||||
|
||||
## Automated Release Process
|
||||
|
||||
### What `release-prepare` Does
|
||||
|
||||
1. **Version Update**: Updates `pyproject.toml` and `markitect/__version__.py`
|
||||
2. **Changelog Generation**: Creates/updates `CHANGELOG.md` from git commits
|
||||
3. **Validation**: Ensures repository is ready for release
|
||||
|
||||
### What `release-publish` Does
|
||||
|
||||
1. **Package Building**: Creates source distribution and wheel
|
||||
2. **Git Tagging**: Creates annotated git tag (e.g., `v1.0.0`)
|
||||
3. **Tag Push**: Pushes tag to remote repository
|
||||
|
||||
## Manual Release Process
|
||||
|
||||
If you prefer manual control:
|
||||
|
||||
### 1. Update Version
|
||||
|
||||
```bash
|
||||
# Edit pyproject.toml
|
||||
version = "1.0.0"
|
||||
|
||||
# Edit markitect/__version__.py
|
||||
__version__ = "1.0.0"
|
||||
```
|
||||
|
||||
### 2. Update Changelog
|
||||
|
||||
Edit `CHANGELOG.md` to add release notes for the new version.
|
||||
|
||||
### 3. Commit Changes
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "Prepare release 1.0.0"
|
||||
```
|
||||
|
||||
### 4. Build Packages
|
||||
|
||||
```bash
|
||||
make release-build
|
||||
```
|
||||
|
||||
### 5. Create Git Tag
|
||||
|
||||
```bash
|
||||
git tag -a v1.0.0 -m "Release 1.0.0"
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
## Distribution
|
||||
|
||||
### Package Types
|
||||
|
||||
MarkiTect releases include:
|
||||
|
||||
- **Source Distribution** (`.tar.gz`): Full source code package
|
||||
- **Wheel** (`.whl`): Pre-built binary package for faster installation
|
||||
|
||||
### Installation Methods
|
||||
|
||||
Users can install MarkiTect in several ways:
|
||||
|
||||
```bash
|
||||
# From PyPI (when published)
|
||||
pip install markitect
|
||||
|
||||
# From wheel file
|
||||
pip install markitect-1.0.0-py3-none-any.whl
|
||||
|
||||
# From source
|
||||
pip install markitect-1.0.0.tar.gz
|
||||
|
||||
# Development installation
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### Release Artifacts
|
||||
|
||||
Each release creates:
|
||||
|
||||
- Source and wheel packages in `dist/`
|
||||
- Git tag (e.g., `v1.0.0`)
|
||||
- Updated `CHANGELOG.md`
|
||||
- Updated version files
|
||||
|
||||
## Changelog Format
|
||||
|
||||
The automated changelog generation categorizes commits:
|
||||
|
||||
### Commit Prefixes
|
||||
|
||||
- `feat:` or `feature:` → **Added** section
|
||||
- `fix:` or `bugfix:` → **Fixed** section
|
||||
- `docs:` or `doc:` → **Documentation** section
|
||||
- Other commits → **Other** section
|
||||
|
||||
### Example Changelog Entry
|
||||
|
||||
```markdown
|
||||
## [1.0.0] - 2025-10-03
|
||||
|
||||
### Added
|
||||
- feat: add template rendering system
|
||||
- feature: implement cache management commands
|
||||
|
||||
### Fixed
|
||||
- fix: resolve test isolation issues
|
||||
- bugfix: correct version information display
|
||||
|
||||
### Documentation
|
||||
- docs: add comprehensive installation guide
|
||||
- doc: update API documentation
|
||||
|
||||
### Other
|
||||
- chore: cleanup repository structure
|
||||
- refactor: improve code organization
|
||||
```
|
||||
|
||||
## Release Checklist
|
||||
|
||||
### Pre-Release
|
||||
|
||||
- [ ] All tests passing (`make test`)
|
||||
- [ ] No uncommitted changes
|
||||
- [ ] On `main` branch
|
||||
- [ ] Version number decided
|
||||
- [ ] Release notes ready
|
||||
|
||||
### Release Process
|
||||
|
||||
- [ ] Run `make release-prepare VERSION=x.y.z`
|
||||
- [ ] Review generated changelog
|
||||
- [ ] Commit changes
|
||||
- [ ] Run `make release-publish VERSION=x.y.z`
|
||||
- [ ] Verify packages created
|
||||
- [ ] Verify git tag created
|
||||
|
||||
### Post-Release
|
||||
|
||||
- [ ] Packages available in `dist/`
|
||||
- [ ] Git tag pushed to remote
|
||||
- [ ] Changelog updated
|
||||
- [ ] Version information correct
|
||||
- [ ] Installation tested
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Validation Failures**
|
||||
```bash
|
||||
# Check what's wrong
|
||||
make release-validate
|
||||
|
||||
# Force release if needed
|
||||
python release.py prepare --version 1.0.0 --force
|
||||
```
|
||||
|
||||
2. **Build Failures**
|
||||
```bash
|
||||
# Install build dependencies
|
||||
pip install build
|
||||
|
||||
# Clean and rebuild
|
||||
rm -rf dist/ build/
|
||||
make release-build
|
||||
```
|
||||
|
||||
3. **Git Issues**
|
||||
```bash
|
||||
# Check git status
|
||||
git status
|
||||
|
||||
# Commit changes
|
||||
git add -A && git commit -m "Prepare release"
|
||||
```
|
||||
|
||||
4. **Version Conflicts**
|
||||
```bash
|
||||
# Check current version
|
||||
make release-status
|
||||
|
||||
# Use correct version number
|
||||
make release-prepare VERSION=1.0.1 # Must be > current
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
```bash
|
||||
# Release tool help
|
||||
python release.py --help
|
||||
|
||||
# Makefile targets
|
||||
make help
|
||||
|
||||
# Command-specific help
|
||||
python release.py prepare --help
|
||||
```
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
The release tools are designed to work with automated CI/CD pipelines:
|
||||
|
||||
```yaml
|
||||
# Example GitHub Actions workflow
|
||||
- name: Create Release
|
||||
run: |
|
||||
make release-prepare VERSION=${{ github.event.inputs.version }}
|
||||
git add -A
|
||||
git commit -m "Prepare release ${{ github.event.inputs.version }}"
|
||||
make release-publish VERSION=${{ github.event.inputs.version }}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Release artifacts should be signed
|
||||
- Use trusted publishing methods
|
||||
- Verify package contents before distribution
|
||||
- Keep release tools and dependencies updated
|
||||
|
||||
## Support
|
||||
|
||||
For release-related issues:
|
||||
|
||||
1. Check this documentation
|
||||
2. Run `make release-status` for diagnostics
|
||||
3. Use `--dry-run` to test changes
|
||||
4. Report issues on the project tracker
|
||||
Reference in New Issue
Block a user