README.rst

Overview

This file serves as a **guide and specification** for creating "newsfragments" within the project. Newsfragments are small ReStructuredText (ReST)-formatted files that document user-facing changes and enhancements. These fragments are later aggregated into the project's official `CHANGELOG`, which is intended primarily for users rather than internal developers.

The primary purpose of this file is to provide clear instructions and conventions on how contributors should write and name these newsfragments to ensure consistency, clarity, and usefulness of the changelog entries.

Key functionalities described in this file include:

The required format and style of newsfragment content.
The naming convention for newsfragment files based on issue numbers and change types.
Guidelines on selecting appropriate change categories.
Tips for maintaining readability and usefulness in the changelog.
Integration notes on how the changelog is built and previewed using project tools.

Detailed Explanation

Newsfragments

Newsfragments are individual `.rst` files that document changes in a concise and user-oriented manner.

Content Style:
- Written in ReST format.
- Use full sentences in past or present tense.
- Include punctuation and examples where helpful.
- Avoid overly technical or developer-centric descriptions.
- Preserve paragraphs and formatting such as code blocks and lists.
Naming Convention:
Each newsfragment file name must follow the pattern:
```
<ISSUE>.<TYPE>.rst
```
- <ISSUE>: The issue or pull request number associated with the change.
- <TYPE>: One of the predefined categories describing the nature of the change.

Change Types:

The allowed types are:

Type	Description
`feature`	New user-facing features (e.g., new CLI options, new behaviors).
`improvement`	Enhancements to existing functionality (e.g., improved output formats).
`bugfix`	Bug fixes.
`doc`	Documentation improvements.
`deprecation`	Features marked as deprecated.
`breaking`	Changes that may break existing user suites (e.g., feature removals).
`vendor`	Changes in vendored packages within the project.
`packaging`	Notes related to packaging, tooling, or runtime assumptions.
`contrib`	Contributor experience improvements (e.g., test running, docs building).
`misc`	Miscellaneous changes not covered by other types.

Additional Notes:
- If no issue number exists, contributors can use the pull request (PR) number after submission.
- When uncertain about the category, contributors are encouraged to ask during the PR process.
- For non-feature entries, keeping the message concise (usually one paragraph) is preferred.
- The tool towncrier is used to preserve formatting and aggregate newsfragments.

Building and Previewing the Changelog

Run the command:
```
tox -e docs
```
to build the project documentation including a draft changelog preview located at:
```
doc/en/_build/html/changelog.html
```
This helps contributors verify how their newsfragment will appear in the final release notes.

Implementation Details and Algorithms

This file itself is a plain text instructional document and does not contain executable code, classes, or functions.

However, it describes integration with the `towncrier` tool, which automates:

Reading all newsfragment files.
Preserving their formatting.
Composing a consolidated changelog for releases.

The naming conventions and formatting rules facilitate automated parsing and classification by `towncrier`, ensuring consistent and accurate changelog generation.

Interactions with Other System Components

towncrier: This file's conventions directly affect how towncrier reads and composes the changelog.
Project's Documentation Build System: The tox -e docs command integrates the generated changelog into the project's documentation.
Issue Tracker / Version Control System: The <ISSUE> or PR number in filenames links changelog entries to tracked changes.
Contributors and Reviewers: This file acts as a guideline to standardize contributions and streamline changelog maintenance.

Visual Diagram

The following Mermaid class diagram illustrates the conceptual structure of the "newsfragment" files as described in this documentation, focusing on the naming scheme and content attributes:

classDiagram
    class NewsFragment {
        +int issue_number
        +ChangeType type
        +string content
        +formatContent()
        +validateNaming()
    }

    class ChangeType {
        <<enumeration>>
        feature
        improvement
        bugfix
        doc
        deprecation
        breaking
        vendor
        packaging
        contrib
        misc
    }

    NewsFragment o-- ChangeType : categorizes >

NewsFragment represents an individual newsfragment file with properties:
- issue_number: the associated issue or PR number.
- type: the category of change.
- content: the ReST-formatted text describing the change.
Methods like formatContent() and validateNaming() conceptually represent the formatting and naming rules enforced.
ChangeType is an enumeration of allowed change categories.

Usage Example

Assuming a contributor fixes an issue numbered 456 that corrects a bug related to output formatting, they would:

Create a file named:
```
456.bugfix.rst
```

Write the content in ReST format, for example:

Fixed an issue where output formatting was incorrect for sequences.

Submit the file as part of their PR.
After merging, the changelog will include this entry under the bugfix section.

Summary

This file is a critical guideline document for maintaining consistent, user-centric changelog entries via newsfragments. It ensures that contributors provide clear, standardized descriptions of changes, which are then automatically aggregated by tooling to produce polished release notes for end users.

--- End of Documentation ---