Metadata-Version: 2.5
Name: release-creator
Version: 0.3.0
Summary: Release preparation tools for changelogs and GitHub
Project-URL: Documentation, https://release-creator.readthedocs.io/
Project-URL: Source, https://github.com/tox-dev/release-creator
Project-URL: Tracker, https://github.com/tox-dev/release-creator/issues
Author-email: Bernát Gábor <gaborjbernat@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: GitHub releases,changelog,release automation,release notes,towncrier
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.15
Requires-Dist: mdformat-gfm<2,>=1
Requires-Dist: mdformat<2,>=1
Description-Content-Type: text/markdown

# release-creator

![release-creator logo](https://raw.githubusercontent.com/tox-dev/release-creator/main/docs/_static/logo-128.png)

[![PyPI](https://img.shields.io/pypi/v/release-creator?style=flat-square)](https://pypi.org/project/release-creator/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/release-creator.svg)](https://pypi.org/project/release-creator/)
[![check](https://github.com/tox-dev/release-creator/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/release-creator/actions/workflows/check.yaml)

Release preparation tools for Python projects. The `notes` command renders a tagged changelog section for a GitHub
Release. Other release tasks can use separate commands.

The [documentation](https://release-creator.readthedocs.io/) has a tutorial, how-to guides, a generated command
reference, and an explanation of the changelog format.

## Render GitHub Release notes

Run the current release from PyPI:

```bash
uvx --from 'release-creator' release-creator notes \
  --changelog docs/changelog.md \
  --tag 1.2.3 \
  --repository tox-dev/example \
  --previous 1.2.2 \
  --artifact-url https://pypi.org/project/example/1.2.3/ > release-notes.md
```

For automation, replace `release-creator` after `--from` with a tested `release-creator==VERSION`. The command reads the
tagged section, maps `Added` to `Features` and `Fixed` to `Bug fixes`, changes linked author handles to GitHub mentions,
and leaves bullets unwrapped. It keeps stable category anchors, omits empty categories when they are absent from the
source, and adds artifact and comparison links. Use `--artifact-label` for an ecosystem other than PyPI; omit
`--artifact-url` when there is no external artifact.

The command also accepts a `.rst` changelog with the same category names. For projects whose `:issue:` role points at
PRs, pass `--issue-role pull`:

```bash
uvx --from 'release-creator' release-creator notes \
  --changelog docs/changelog.rst \
  --tag 1.2.3 \
  --repository tox-dev/example \
  --previous 1.2.2 \
  --issue-role pull \
  --artifact-url https://pypi.org/project/example/1.2.3/ > release-notes.md
```

The changelog is the source of truth. The command does not infer changes from commits or generate an author list. Add
verified human credits to changelog entries before release; omit bot credits. The GitHub Release may add a
`New Contributors` section by passing `--generated-notes` with the body from GitHub's generate-notes API. Only handles
credited in the changelog are kept; the generated-notes banner and other generated sections are discarded.

Named Towncrier fragments need no issue or PR number. Before Towncrier builds the changelog, run
`release-creator fragments --repository owner/repo --git`. The command reads each fragment's introducing squash commit,
adds its PR link, and fails if the subject does not end in `(#number)`. For a checkout without Git history, pass a
tab-separated subject map with `--commit-map commits.tsv` instead.

The `tags` command calculates a version from pending fragments, validates numeric tags, and selects the preceding tag
for GitHub comparisons:

```bash
git tag --list | uvx --from 'release-creator' release-creator tags --next auto
git tag --list | uvx --from 'release-creator' release-creator tags 1.2.3 --require-newer
git tag --list | uvx --from 'release-creator' release-creator tags 1.2.3 --previous
```

## Development and releases

See [contributing](https://github.com/tox-dev/release-creator/blob/main/CONTRIBUTING.md) for the fragment format and release process. The package uses the same `notes`
command for its own GitHub Releases. Run `tox -e 3.15,type,pkg_meta,docs` and `prek run --all-files` before a PR.
