Skip to content

Release Management Guide

This document provides comprehensive instructions for releasing fnb (Fetch'n'Backup) to PyPI, including version management, testing procedures, and deployment workflows.

Table of Contents

Release Overview

The fnb project uses semantic versioning with automated workflows for: - Version Management: Automated with commitizen - Testing: Unit and integration tests with 87% coverage - Building: Using uv build system with hatchling backend - Deployment: TestPyPI for testing, PyPI for production - Documentation: Automated changelog generation

Release Types

  • Patch Release (0.10.1): Bug fixes and minor improvements
  • Minor Release (0.11.0): New features, backward compatible
  • Major Release (1.0.0): Breaking changes (when ready)

Prerequisites

Environment Setup

  1. Development Environment 

    # Ensure clean working directory
git status

# Update to latest main branch
git checkout main
git pull origin main

  2. Required Tools

  3. Python 3.12+
  4. uv package manager
  5. GitLab CLI (glab)

  6. Task runner (task)

  7. API Tokens Configuration

Create .env file in project root: 

# PyPI Production API Token
PYPI_API_TOKEN=pypi-your-production-token-here

# TestPyPI API Token
TESTPYPI_API_TOKEN=pypi-your-testpypi-token-here

⚠️ Security Note: Never commit API tokens to version control. Add .env to .gitignore.

API Token Setup

  1. PyPI Production Token
  2. Visit https://pypi.org/manage/account/token/
  3. Create token with scope limited to fnb project

  4. Add to .env as PYPI_API_TOKEN

  5. TestPyPI Token

  6. Visit https://test.pypi.org/manage/account/token/
  7. Create token with scope limited to fnb project
  8. Add to .env as TESTPYPI_API_TOKEN

Version Management

Automated Version Bumping

The project uses commitizen for automated version management:

# Preview version changes (dry run)
task version

# Execute version bump with changelog update
task version:bump

Manual Version Configuration

Files automatically updated during version bump: - pyproject.toml:version - src/fnb/__init__.py:__version__ - CHANGELOG.md (conventional commits)

Version Scheme

[tool.commitizen]
name = "cz_conventional_commits"
version = "0.10.0"
tag_format = "$version"
version_scheme = "semver"
update_changelog_on_bump = true
major_version_zero = true

Release Workflows

Complete automated workflow for most releases:

# Complete release workflow (test → format → bump → release)
task release:full

This command performs: 1. Runs all tests including integration tests 2. Formats code with ruff 3. Runs pre-commit hooks 4. Bumps version and updates changelog 5. Creates GitLab release with tags

2. Step-by-Step Release

For more control over the release process:

# Step 1: Run comprehensive tests
task test

# Step 2: Format code and run quality checks
task lint
task lint:pre-commit

# Step 3: Preview version changes
task version

# Step 4: Bump version
task version:bump

# Step 5: Create GitLab release
task release

3. Development Testing Workflow

Before creating a release, test the complete CI pipeline locally:

# Simulate complete CI pipeline
task test:ci

# This runs:
# - Unit tests with coverage
# - Code formatting checks
# - Pre-commit hooks

PyPI Deployment

Always test deployment to TestPyPI before production:

# Deploy to TestPyPI
task publish:test

Production PyPI Deployment

After successful TestPyPI verification:

# Deploy to production PyPI
task publish:prod

Deployment Process Details

Both deployment commands perform: 1. Build: uv build creates wheel and source distribution 2. Upload: uv publish uploads to respective PyPI repository 3. Validation: Automatic package validation by PyPI

Testing and Verification

TestPyPI Verification

After TestPyPI deployment, verify the package:

# Verify specific version (replace x.y.z with actual version)
VERSION=x.y.z task verify:testpypi

The verification process: 1. Creates isolated test environment in /tmp/fnb-test 2. Installs package from TestPyPI 3. Tests core functionality: - fnb version command - fnb --help command - fnb init --help command - Module import verification 4. Reports verification status

Manual Verification

You can also verify manually:

# Create test environment
cd /tmp
python3 -m venv test-fnb
source test-fnb/bin/activate

# Install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ \
           --extra-index-url https://pypi.org/simple/ \
           fnb==x.y.z

# Test basic functionality
fnb --help
fnb version
fnb init --help

# Cleanup
deactivate
rm -rf test-fnb

Production Verification

After PyPI deployment, verify with:

# Install from production PyPI
pip install fnb==x.y.z

# Test functionality
fnb --help
fnb version

Troubleshooting

Common Issues

  1. Build Failures 

    # Check build environment
uv build --verbose

# Common fixes:
# - Update pyproject.toml metadata
# - Check version consistency
# - Verify dependency specifications

  2. Upload Failures 

    # Check API token validity
echo $PYPI_API_TOKEN
echo $TESTPYPI_API_TOKEN

# Verify token permissions in PyPI account settings

  3. Version Conflicts 

    # Check current version
cat pyproject.toml | grep version
cat src/fnb/__init__.py | grep __version__

# Force version consistency
task version:bump

  4. Test Failures 

    # Run tests with verbose output
task test:unit -v

# Check coverage report
open htmlcov/index.html

Recovery Procedures

  1. Failed Release Recovery 

    # If release failed after version bump
git reset --hard HEAD~1  # Reset to before version bump

# Or fix issues and retry
task release

  2. PyPI Upload Failure Recovery 

    # Delete failed packages (if possible)
# Fix issues in code/configuration
# Increment version and retry
task version:bump
task publish:test  # Always test first

Automated CI/CD

GitLab CI Integration

The project includes automated workflows:

  1. Automatic TestPyPI Deployment
  2. Triggered on git tag push
  3. Runs complete test suite

  4. Deploys to TestPyPI automatically

  5. Manual Production Deployment

  6. Use task publish:prod after TestPyPI verification
  7. Requires manual execution for safety

CI Configuration

GitLab CI automatically: - Runs unit and integration tests - Checks code formatting - Validates package metadata - Deploys to TestPyPI on tag creation

Release Checklist

Pre-Release

  • [ ] All tests passing (task test)
  • [ ] Code formatted (task lint)
  • [ ] Pre-commit hooks pass (task lint:pre-commit)
  • [ ] Documentation updated
  • [ ] CHANGELOG.md reviewed
  • [ ] API tokens configured in .env

Release Process

  • [ ] Version bumped (task version:bump)
  • [ ] GitLab release created (task release)
  • [ ] TestPyPI deployment successful (task publish:test)
  • [ ] TestPyPI verification passed (VERSION=x.y.z task verify:testpypi)
  • [ ] Production PyPI deployment (task publish:prod)
  • [ ] Production verification completed

Post-Release

  • [ ] Release announcement (if needed)
  • [ ] Documentation site updated
  • [ ] Issue tracker updated
  • [ ] Next development cycle planned

Release Schedule

Regular Releases

  • Patch Releases: As needed for bug fixes
  • Minor Releases: Monthly or when feature-complete
  • Major Releases: When breaking changes are necessary

Emergency Releases

For critical security or functionality issues: 1. Create hotfix branch 2. Implement minimal fix 3. Fast-track testing and review 4. Emergency release deployment

Best Practices

Development

  • Use conventional commits for automatic changelog generation
  • Maintain high test coverage (target: 87%+)
  • Test all changes in TestPyPI before production
  • Review changelogs before release

Security

  • Never commit API tokens
  • Use minimal-scope API tokens
  • Regularly rotate API tokens
  • Monitor release notifications

Documentation

  • Update documentation with releases
  • Maintain accurate installation instructions
  • Document breaking changes clearly
  • Provide migration guides for major releases

Support and Contact

For release-related issues: - Bug Reports: https://gitlab.com/qumasan/fnb/-/issues - Documentation: https://qumasan.gitlab.io/fnb/ - Merge Requests: https://gitlab.com/qumasan/fnb/-/merge_requests

Last Updated: 2025-08-21 (v0.10.0) Document Version: 1.0.0