markitect-main/RELEASE.md

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:

# 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

# Check current release status
make release-status

# Validate repository for release
make release-validate

Release Preparation

# 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

# 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:

• 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

# 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:

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

# 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

git add -A
git commit -m "Prepare release 1.0.0"

4. Build Packages

make release-build

5. Create Git Tag

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:

# 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

## [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

   # Check what's wrong
   make release-validate
   
   # Force release if needed
   python release.py prepare --version 1.0.0 --force
   

2. Build Failures

   # Install build dependencies
   pip install build
   
   # Clean and rebuild
   rm -rf dist/ build/
   make release-build
   

3. Git Issues

   # Check git status
   git status
   
   # Commit changes
   git add -A && git commit -m "Prepare release"
   

4. Version Conflicts

   # Check current version
   make release-status
   
   # Use correct version number
   make release-prepare VERSION=1.0.1  # Must be > current
   

Getting Help

# 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:

# 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