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:

```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