This directory contains "newsfragments" which are short files that contain a small ReST-formatted text that will be added to the next CHANGELOG.

The CHANGELOG will be read by users, so this description should be aimed to pytest users instead of describing internal changes which are only relevant to the developers.

Make sure to use full sentences in the past or present tense and use punctuation, examples:

Improved verbose diff output with sequences.

Terminal summary statistics now use multiple colors.

Each file should be named like <ISSUE>.<TYPE>.rst, where <ISSUE> is an issue number, and <TYPE> is one of:

• feature: new user facing features, like new command-line options and new behavior.
• improvement: improvement of existing functionality, usually without requiring user intervention (for example, new fields being written in --junit-xml, improved colors in terminal, etc).
• bugfix: fixes a bug.
• doc: documentation improvement, like rewording an entire session or adding missing docs.
• deprecation: feature deprecation.
• breaking: a change which may break existing suites, such as feature removal or behavior change.
• vendor: changes in packages vendored in pytest.
• packaging: notes for downstreams about unobvious side effects and tooling. changes in the test invocation considerations and runtime assumptions.
• contrib: stuff that affects the contributor experience. e.g. Running tests, building the docs, setting up the development environment.
• misc: changes that are hard to assign to any of the above categories.

So for example: 123.feature.rst, 456.bugfix.rst.

Tip

See :file:`pyproject.toml` for all available categories (tool.towncrier.type).

If your PR fixes an issue, use that number here. If there is no issue, then after you submit the PR and get the PR number you can add a changelog using that instead.

If you are not sure what issue type to use, don't hesitate to ask in your PR.

towncrier preserves multiple paragraphs and formatting (code blocks, lists, and so on), but for entries other than features it is usually better to stick to a single paragraph to keep it concise.

You can also run tox -e docs to build the documentation with the draft changelog (doc/en/_build/html/changelog.html) if you want to get a preview of how your change will look in the final release notes.