RELEASING.rst

Overview

This document outlines the official procedure and policies for releasing new versions of the `pytest` software project. It provides detailed instructions for both automated and manual release workflows, covering bug-fix, minor, major, and release candidate versions. The purpose of this file is to ensure consistent, reliable, and efficient release processes that balance timely delivery of fixes and features with quality control.

Key functionalities include:

This file serves as the authoritative guide for maintainers and contributors involved in the release process.

Detailed Explanation of Sections

1. Release Policy and Branch Setup

This ensures that contributors correctly push branches and interact with the official repo.

2. Preparing: Automatic Method

This section describes the GitHub Actions-based automation for preparing release pull requests (PRs).

3. Preparing: Manual Method

If automation is not used, releases can be prepared manually (Linux environment required).

**Steps:**

  1. Create and push maintenance branch for major/minor releases:

    git fetch upstream
git branch MAJOR.MINOR.x upstream/main
git push upstream MAJOR.MINOR.x

  2. Create a release branch from the maintenance branch:

    git checkout -b release-MAJOR.MINOR.PATCH MAJOR.MINOR.x

  3. Generate documentation, changelog, and announcements using tox:

    tox -e release -- MAJOR.MINOR.PATCH

  4. Push changes and open a PR targeting the maintenance branch.

4. Releasing (Post-PR Approval)

Once the PR is approved and tests pass:

  1. Trigger the deployment workflow on GitHub Actions (deploy.yml) using the release branch.

    CLI example:

    gh workflow run deploy.yml -R pytest-dev/pytest --ref=release-MAJOR.MINOR.PATCH -f version=MAJOR.MINOR.PATCH

  2. The deploy job publishes the release to PyPI and tags the repository. Approval by pytest-dev/core is required.

  3. Merge the release PR without squash merging to preserve the tagged commit in main.

  4. Cherry-pick changelog and announcement commits to main:

    git fetch upstream
git checkout upstream/main -b cherry-pick-release
git cherry-pick -x -m1 upstream/MAJOR.MINOR.x

  5. Open and merge a PR for cherry-pick-release after CI passes.

  6. For major and minor releases (or first prerelease), tag a dev version on main for the next feature cycle:

    git checkout main
git pull
git tag MAJOR.{MINOR+1}.0.dev0
git push upstream MAJOR.{MINOR+1}.0.dev0

  7. Send an email announcement using the contents from doc/en/announce/release-<VERSION>.rst to Python mailing lists and social media.

Important Implementation Details

Interaction with Other Parts of the System

Usage Examples Summary

Visual Diagram

The following flowchart depicts the automated release preparation workflow and subsequent release steps, highlighting key decision points and interactions:

flowchart TD
    A[Trigger prepare-release-pr.yml workflow] --> B{Is 'major release' input 'yes'?}
    B -- Yes --> C[Increment major version]
    B -- No --> D{Any .feature.rst or .breaking.rst files?}
    D -- Yes --> E[Increment minor version]
    D -- No --> F[Increment patch version]
    C --> G{Is 'prerelease' input set?}
    E --> G
    F --> G
    G -- Yes --> H[Append prerelease suffix to version]
    G -- No --> I[Use version as is]
    H --> J[Create PR branch release-MAJOR.MINOR.PATCH]
    I --> J
    J --> K[Open PR for release branch]
    K --> L{PR approved and tests pass?}
    L -- Yes --> M[Trigger deploy.yml workflow]
    M --> N[Publish to PyPI & tag repo]
    N --> O[Merge PR without squash]
    O --> P[Cherry-pick changelog to main]
    P --> Q[Tag dev version for next release]
    Q --> R[Send release announcements]

This diagram clarifies the automated decision logic for version increments and illustrates the release pipeline from PR creation to announcement.

This comprehensive document ensures all maintainers and contributors understand the release workflow, adhere to best practices, and maintain release quality and consistency.