Introduce towncrier (#1201)

* Introduce towncrier with basic configuration

* Format changelog according to keep a changelog

* Add pre-commit hook

* Add changelog entry

* Update PR template

* Switch to default fragment types

* Update .github/PULL_REQUEST_TEMPLATE.md

Co-authored-by: chrysle <fritzihab@posteo.de>

* Update news contribution docs

* Update bump changelog workflow

* Remove redundant news fragments

* Add empty gitignore file to make sure changelog.d folder is tracked

* Apply suggestions from code review

Co-authored-by: chrysle <fritzihab@posteo.de>

* Add changelog entry

* Build changelog during `build_docs` nox command

* Moved towncrier changelog entry to docs block

* Stop adding version number to top of changelog via mkdocs script

* Render current newsfragments cleanly during build docs

* Remove extra stdout lines from towncrier build step

* Add draft changelog file to gitignore

* Add upcoming changes to prod changelog

* Remove draft changelog in site after build

* Create news fragment for current dev changelog

---------

Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>
Co-authored-by: chrysle <fritzihab@posteo.de>

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,6 @@
 <!-- add an 'x' in the brackets below -->
 
-- [ ] I have added an entry to `docs/changelog.md`
+- [ ] I have added a news fragment under `changelog.d/` (if the patch affects the end users)
 
 ## Summary of changes
 

.github/workflows/tests.yml

@@ -139,7 +139,7 @@ jobs:
       - name: Create pull request branch
         run: git switch -c "bump-changelog-for-${RELEASE_VERSION}"
       - name: Update changelog
-        run: echo -e "## dev\n\n## $RELEASE_VERSION\n$(tail -n +2 CHANGELOG.md)" > CHANGELOG.md
+        run: pipx run towncrier build --yes --version $RELEASE_VERSION
       - name: Commit and push change
         run: |
           git config --global user.name 'github-actions[bot]'

.gitignore

@@ -15,3 +15,4 @@ __pycache__
 build
 *.whl
 /pipx.1
+/docs/_draft_changelog.md

CONTRIBUTING.md

@@ -3,6 +3,42 @@ Thanks for your interest in contributing to pipx!
 Everyone who interacts with the pipx project via codebase, issue tracker, chat rooms, or otherwise is expected to follow
 the [PSF Code of Conduct](https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md).
 
+
+## Submitting changes
+
+1. Fork [the GitHub repository](https://github.com/pypa/pipx).
+2. Make a branch off of `main` and commit your changes to it.
+3. Add a changelog entry.
+4. Submit a pull request to the `main` branch on GitHub, referencing an
+   open issue.
+
+### Changelog entries
+
+The `CHANGELOG.md` file is built by
+[towncrier](https://pypi.org/project/towncrier/) from news fragments in the
+`changelog.d/` directory. To add an entry, create a news fragment in that directory
+named `{number}.{type}.md`, where `{number}` is the issue number,
+and `{type}` is one of `feature`, `bugfix`, `doc`, `removal`, or `misc`.
+
+For example, if your issue number is 1234 and it's fixing a bug, then you
+would create `changelog.d/1234.bugfix.md`. PRs can span multiple
+categories by creating multiple files: if you added a feature and
+deprecated/removed an old feature for issue #5678, you would create
+`changelog.d/5678.feature.md` and `changelog.d/5678.removal.md`.
+
+A changelog entry is meant for end users and should only contain details
+relevant to them. In order to maintain a consistent style, please keep
+the entry to the point, in sentence case, shorter than 80 characters,
+and in an imperative tone. An entry should complete the sentence "This
+change will ...". If one line is not enough, use a summary line in an
+imperative tone, followed by a description of the change in one or more
+paragraphs, each wrapped at 80 characters and separated by blank lines.
+
+You don't need to reference the pull request or issue number in a
+changelog entry, since towncrier will add a link using the number in the
+file name. Similarly, you don't need to add your name to the entry,
+since that will be associated with the pull request.
+
 ## Running pipx For Development
 
 To develop `pipx`, either create a [developer environment](#creating-a-developer-environment), or perform an editable

changelog.d/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/1161.doc.md

@@ -0,0 +1 @@
+Introduce towncrier for managing the changelog

changelog.d/1198.doc.md

@@ -0,0 +1 @@
+Add workaround for using pipx applications in shebang under macOS

mkdocs.yml

@@ -47,3 +47,4 @@ plugins:
   - gen-files:
       scripts:
         - scripts/gen_doc_pages.py
+  - macros

noxfile.py

@@ -1,3 +1,4 @@
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -6,7 +7,7 @@
 
 PYTHON_ALL_VERSIONS = ["3.12", "3.11", "3.10", "3.9", "3.8"]
 PYTHON_DEFAULT_VERSION = "3.12"
-DOC_DEPENDENCIES = ["jinja2", "mkdocs", "mkdocs-material", "mkdocs-gen-files"]
+DOC_DEPENDENCIES = ["jinja2", "mkdocs", "mkdocs-material", "mkdocs-gen-files", "mkdocs-macros-plugin", "towncrier"]
 MAN_DEPENDENCIES = ["argparse-manpage[setuptools]"]
 TEST_DEPENDENCIES = ["pytest", "pypiserver[passlib]", 'setuptools; python_version>="3.12"', "pytest-cov"]
 # Packages whose dependencies need an intact system PATH to compile
@@ -55,6 +56,22 @@ def tests_with_options(session: nox.Session, *, net_pypiserver: bool) -> None:
     session.notify("cover")
 
 
+def create_upcoming_changelog(session: nox.Session) -> Path:
+    draft_changelog_content = session.run("towncrier", "build", "--version", "Upcoming", "--draft", silent=True)
+    draft_changelog = Path("docs", "_draft_changelog.md")
+    if draft_changelog_content and "No significant changes" not in draft_changelog_content:
+        lines_to_keep = draft_changelog_content.split("\n")
+        changelog_start = 0
+        for i, line in enumerate(lines_to_keep):
+            if line.startswith("##"):
+                changelog_start = i
+                break
+        lines_to_keep[changelog_start] = "## Planned for next release"
+        clean_changelog_content = "\n".join(lines_to_keep[changelog_start:])
+        draft_changelog.write_text(clean_changelog_content)
+    return draft_changelog
+
+
 @nox.session(python=PYTHON_ALL_VERSIONS)
 def tests(session: nox.Session) -> None:
     """Tests using local pypiserver only"""
@@ -112,13 +129,19 @@ def build_docs(session: nox.Session) -> None:
     site_dir = session.posargs or ["site/"]
     session.install(*DOC_DEPENDENCIES, ".")
     session.env["PIPX__DOC_DEFAULT_PYTHON"] = "typically the python used to execute pipx"
+    upcoming_changelog = create_upcoming_changelog(session)
     session.run("mkdocs", "build", "--strict", "--site-dir", *site_dir)
+    upcoming_changelog.unlink(missing_ok=True)
+    for site in site_dir:
+        shutil.rmtree(Path(site, "_draft_changelog"))
 
 
 @nox.session(python=PYTHON_DEFAULT_VERSION)
 def watch_docs(session: nox.Session) -> None:
     session.install(*DOC_DEPENDENCIES, ".")
+    upcoming_changelog = create_upcoming_changelog(session)
     session.run("mkdocs", "serve", "--strict")
+    upcoming_changelog.unlink(missing_ok=True)
 
 
 @nox.session(python=PYTHON_DEFAULT_VERSION)

pyproject.toml

@@ -74,6 +74,15 @@ lint.mccabe.max-complexity = 15
 [tool.pytest.ini_options]
 markers = ["all_packages: test install with maximum number of packages"]
 
+[tool.towncrier]
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+start_string = "<!-- towncrier release notes start -->\n"
+underlines = ["", "", ""]
+title_format = "## [{version}](https://github.com/pypa/pipx/tree/{version}) - {project_date}"
+issue_format = "[#{issue}](https://github.com/pypa/pipx/issues/{issue})"
+package = "pipx"
+
 [[tool.mypy.overrides]]
 module = ["pipx.version", "pycowsay.*"]
 ignore_missing_imports = true

scripts/gen_doc_pages.py

@@ -46,8 +46,3 @@ def get_help(cmd: Optional[str]) -> str:
 with mkdocs_gen_files.open("docs.md", "wt") as file_handler:
     file_handler.write(env.get_template("docs.md").render(**params))
     file_handler.write("\n")
-
-with mkdocs_gen_files.open("changelog.md", "rt") as file_handler:
-    text = file_handler.read()
-with mkdocs_gen_files.open("changelog.md", "wt") as file_handler:
-    file_handler.write(f"## {__version__}" + text[len("## dev") :])