Release Process - csed-ucm/psephos GitHub Wiki

Release Process

Overview

The Psephos project follows semantic versioning and uses automated release processes to ensure consistent and reliable deployments.

Semantic Versioning

We follow Semantic Versioning (SemVer) for version numbers:

Format: MAJOR.MINOR.PATCH

  • MAJOR: Breaking changes that are not backward compatible
  • MINOR: New features that are backward compatible
  • PATCH: Bug fixes that are backward compatible

Examples:

  • 1.0.0 → 1.0.1 (bug fix)
  • 1.0.1 → 1.1.0 (new feature)
  • 1.1.0 → 2.0.0 (breaking change)

Release Workflow

1. Development Process

  1. Feature Development: Work on feature branches
  2. Pull Requests: Submit PRs to the microservices branch
  3. Code Review: Team reviews and approves changes
  4. Testing: Automated tests must pass
  5. Merge: PR is merged to microservices

2. Release Preparation

  1. Version Bump: Update version in pyproject.toml
  2. Changelog: Update CHANGELOG.md with new features/fixes
  3. Testing: Run full test suite
  4. Documentation: Update docs if needed

3. Release Creation

  1. Tag Creation: Create git tag with version number
  2. Build: Generate distribution packages
  3. Publish: Deploy to PyPI and Docker Hub
  4. Documentation: Update release documentation

Automated Release Process

GitHub Actions

The project uses GitHub Actions for automated releases:

name: Release
on:
  push:
    tags:
      - 'v*'
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v3
        with:
          python-version: '3.11'
      
      - name: Build package
        run: |
          pip install build
          python -m build
      
      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}
      
      - name: Build Docker image
        run: |
          docker build -t psephos/api:${{ github.ref_name }} .
          docker push psephos/api:${{ github.ref_name }}

Release Triggers

Releases are triggered by:

  • Manual: Creating a tag manually
  • Automatic: Using semantic-release based on commit messages

Building Distributions

Python Package

Build the Python package for PyPI distribution:

# Install build tools
pip install build

# Build source and wheel distributions
python -m build

# Output files in dist/
# - psephos-api-x.y.z.tar.gz (source)
# - psephos_api-x.y.z-py3-none-any.whl (wheel)

Docker Image

Build Docker image for containerized deployment:

FROM python:3.11-alpine

WORKDIR /app

# Copy requirements and install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY app/ ./app/

# Set environment variables
ENV PYTHONPATH=/app

# Expose port
EXPOSE 9000

# Run application
CMD ["uvicorn", "app.app:app", "--host", "0.0.0.0", "--port", "9000"]

Build commands:

# Build image
docker build -t psephos/api:latest .

# Tag for version
docker tag psephos/api:latest psephos/api:v1.2.3

# Push to registry
docker push psephos/api:latest
docker push psephos/api:v1.2.3

Docker Compose Deployment

For complete deployment with MongoDB:

version: '3.8'

services:
  mongodb:
    image: mongo:7
    container_name: psephos-mongodb
    restart: unless-stopped
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: changeme
    volumes:
      - mongodb_data:/data/db

  api:
    image: psephos/api:latest
    container_name: psephos-api
    restart: unless-stopped
    ports:
      - "9000:9000"
    environment:
      MONGODB_URL: mongodb://root:changeme@mongodb:27017
      SECRET_KEY: your-secret-key-here
      ADMIN_EMAIL: [email protected]
    depends_on:
      - mongodb

volumes:
  mongodb_data:

Deploy with:

docker-compose up -d

Release Checklist

Pre-Release

  • All tests passing
  • Code review completed
  • Documentation updated
  • Version number bumped
  • Changelog updated
  • Security scan completed

Release

  • Tag created with correct version
  • Build artifacts generated
  • PyPI package published
  • Docker image built and pushed
  • GitHub release created
  • Documentation deployed

Post-Release

  • Release notes published
  • Team notified
  • Monitoring alerts configured
  • Rollback plan prepared
  • Next version planning started

Hotfix Process

For critical bug fixes that need immediate release:

  1. Branch: Create hotfix branch from latest release tag
  2. Fix: Implement minimal fix for the critical issue
  3. Test: Run focused tests on the fix
  4. Release: Create patch release (increment PATCH version)
  5. Backport: Merge fix back to development branch
# Create hotfix branch
git checkout -b hotfix/v1.2.4 v1.2.3

# Make fix and commit
git commit -m "fix: critical security vulnerability"

# Tag and release
git tag v1.2.4
git push origin v1.2.4

# Merge back to main development branch
git checkout microservices
git merge hotfix/v1.2.4

Version Management

Current Version

Version is managed in pyproject.toml:

[project]
name = "psephos-api"
version = "1.2.3"

Version History

Major releases and their key features:

  • v1.0.0: Initial stable release
  • v1.1.0: WebSocket support added
  • v1.2.0: Enhanced permission system
  • v2.0.0: Microservices architecture (current development)

Deployment Environments

Development

  • Branch: microservices
  • URL: https://dev-api.psephos.example.com
  • Auto-deploy: On every merge to microservices

Staging

  • Branch: Release candidates
  • URL: https://staging-api.psephos.example.com
  • Deploy: Manual trigger before production

Production

  • Branch: Tagged releases
  • URL: https://api.psephos.example.com
  • Deploy: Manual approval required