Your First Release¶

A complete walkthrough of releasing your first version with releasio.

Overview¶

In this guide, you'll:

Set up your project
Make conventional commits
Preview the release
:material-pull-request: Create a release PR
Publish to PyPI

Step 1: Project Setup¶

Ensure Your `pyproject.toml` is Ready¶

releasio reads project metadata from pyproject.toml:

[project]
name = "my-awesome-project"
version = "0.1.0"
description = "An awesome Python project"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Version Location

releasio automatically updates the version field in pyproject.toml. No additional configuration needed.

Initialize Configuration (Optional)¶

Create a configuration file for customization:

releasio init

This creates .releasio.toml with default settings you can customize.

Step 2: Make Commits¶

Use conventional commits for automatic version detection:

# Add a new feature (bumps minor version)
git commit -m "feat: add user registration endpoint"

# Fix a bug (bumps patch version)
git commit -m "fix: validate email format correctly"

# Add documentation (bumps patch version)
git commit -m "docs: add API usage examples"

# Breaking change (bumps major version)
git commit -m "feat!: change authentication flow

BREAKING CHANGE: JWT tokens now required for all endpoints"

Commit Type Reference¶

Type	Version Bump	Use When
`feat`	Minor	Adding new functionality
`fix`	Patch	Fixing bugs
`docs`	Patch	Documentation changes
`perf`	Patch	Performance improvements
`refactor`	Patch	Code refactoring
`test`	Patch	Adding tests
`chore`	Patch	Maintenance tasks
`feat!`	Major	Breaking changes

Step 3: Preview Your Release¶

Before making any changes, preview what will happen:

releasio check

Example Output

╭─ Release Preview ────────────────────────────────────────╮
│                                                          │
│  📦 Project: my-awesome-project                          │
│  📌 Current: v0.1.0                                      │
│  🚀 Next:    v0.2.0 (minor bump)                         │
│                                                          │
│  📝 Commits since v0.1.0:                                │
│                                                          │
│  ✨ Features:                                            │
│    • feat: add user registration endpoint                │
│                                                          │
│  🐛 Bug Fixes:                                           │
│    • fix: validate email format correctly                │
│                                                          │
│  📚 Documentation:                                       │
│    • docs: add API usage examples                        │
│                                                          │
╰──────────────────────────────────────────────────────────╯

This command is always safe - it never modifies any files.

Step 4: Create the Release PR¶

Option A: Local Release PR¶

Create a release PR from your local machine:

releasio release-pr --execute

This will:

Option B: GitHub Actions (Recommended)¶

Set up automatic release PR creation:

.github/workflows/release.yml

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write
  id-token: write

jobs:
  release-pr:
    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: mikeleppane/releasio@v2
        with:
          command: release-pr
          github-token: ${{ secrets.GITHUB_TOKEN }}

Now every push to main automatically creates/updates a release PR!

Step 5: Review and Merge¶

Review the PR¶

The release PR includes:

Version bump - Updated pyproject.toml
Changelog - New entries in CHANGELOG.md
Summary - List of changes in PR description

Example PR Description

## 🚀 Release v0.2.0

### ✨ Features
- Add user registration endpoint (#42)

### 🐛 Bug Fixes
- Validate email format correctly (#43)

### 📚 Documentation
- Add API usage examples (#44)

---
*This PR was automatically created by releasio*

Merge the PR¶

Once you're happy with the changes, merge the PR. This triggers the release!

Step 6: Automatic Release¶

When the release PR is merged, the release workflow runs: