changelog.rst

Overview

The `changelog.rst` file serves as the official changelog documentation for the pytest project. It provides a detailed, chronological record of all notable changes, improvements, bug fixes, new features, deprecations, and removals introduced in each released version of pytest. The changelog follows the [Semantic Versioning](https://semver.org/) scheme (`..`), where backward-incompatible changes are only introduced in major versions with advance notice.

This file is automatically managed by the Towncrier tool, which aggregates change fragments from the development process and compiles them into this single changelog document. Contributors are discouraged from manually adding new changelog entries here and should instead add news fragments to the appropriate news folder as per pytest's contribution guidelines.

Purpose and Functionality

• Purpose: To communicate clearly and transparently the evolution of pytest across its versions to users, developers, downstream packagers, and contributors.

• Functionality: Presents structured release notes including categories like:

  • Breaking changes and removals

  • Deprecations

  • New features

  • Improvements in existing functionality

  • Bug fixes

  • Documentation improvements

  • Packaging updates

  • Contributor-facing changes

  • Miscellaneous internal changes

Structure and Content Details

Each release section in the changelog documents:

1. Version and Release Date: The version number and the date of release.

2. Breaking Changes / Removals: Incompatible changes that may require user action.

3. Deprecations: Features planned for removal in future major versions.

4. Features: New capabilities added.

5. Improvements: Enhancements to existing functionalities.

6. Bug Fixes: Corrections of defects.

7. Improved Documentation: Updates or clarifications to docs.

8. Packaging Updates: Changes affecting distribution or integration.

9. Contributor-facing Changes: Changes relevant to pytest contributors.

10. Miscellaneous Internal Changes: Internal refactors or minor adjustments.

The entries often include:

• Issue or pull request numbers referenced via GitHub links.

• Explanatory notes and rationale behind changes.

• Code snippets or examples illustrating new features or fixes.

• Cross-references to the official documentation for further details.

Example Usage

While this file is not a source code file and thus contains no classes or functions, it is a vital reference point for:

• Users upgrading pytest to understand what has changed.

• Developers who want to track the introduction of features or work around deprecated behaviors.

• Package maintainers who need to adjust packaging or dependency requirements.

• Contributors adding new features or fixes, to ensure coherent and standardized changelog entries.

Important Implementation Details

• Towncrier Integration: The changelog is generated by Towncrier from individual news fragments during each release cycle. This ensures consistency and reduces merge conflicts in changelog maintenance.

• Semantic Versioning Compliance: Ensures users can anticipate the impact of upgrading based on version numbering.

• Extensive Historical Record: The file contains detailed entries dating back multiple major releases, providing a comprehensive history.

• Formatting: Uses reStructuredText (RST) markup for integration with Sphinx documentation tooling, enabling easy rendering in HTML or PDF formats.

Interaction with Other Parts of the System

• Development Workflow: When developers submit pull requests, they add news fragments in designated folders following the guidelines linked within the changelog (https://pip.pypa.io/en/latest/development/contributing/#news-entries).

• Documentation Build: During the documentation build process, the changelog is included and formatted as part of the official pytest documentation website.

• Release Process: The changelog is updated automatically during release preparation by Towncrier, ensuring that release notes are accurate and complete.

Visual Diagram: Changelog File Structure and Workflow

This file is a utility/documentation file, so a flowchart illustrating the process of changelog update and release integration is most suitable.

flowchart TD
    A[Developer submits PR with code changes] --> B[Add news fragment in news folder]
    B --> C[Towncrier collects news fragments]
    C --> D[Generate changelog.rst with aggregated entries]
    D --> E[Release Manager reviews changelog]
    E --> F[Release pytest version with updated changelog]
    F --> G[Users consult changelog for release notes]

Summary

• changelog.rst is a comprehensive and authoritative record of changes in pytest.

• It is maintained automatically by Towncrier from individual news fragments added during development.

• The file uses Semantic Versioning and categorizes changes for clarity.

• It is crucial for communication between pytest developers, users, and maintainers.

• It is integrated into the pytest documentation build and release workflows.

Because this is a documentation file, it contains no classes or functions directly, but it plays a critical role in the pytest project's lifecycle and user communication.

**Note:** To add new changelog entries, contributors should add news fragments to the configured news folder and not edit `changelog.rst` directly.