Merge pull request #157 from nicoddemus/towncrier

Use towncrier and a custom tox environment to prepare a release

Author: nicoddemus

HOWTORELEASE.rst

@@ -1,9 +1,13 @@
 Release Procedure
 -----------------
 
-#. Update the ``CHANGELOG.rst`` for the new release and commit.
+#. From a clean work tree, execute::
 
-#. Open a PR named ``release-X.Y.Z`` targeting ``master``.
+    tox -e release -- VERSION
+
+   This will create the branch ready to be pushed.
+
+#. Open a PR targeting ``master``.
 
 #. All tests must pass and the PR must be approved by at least another maintainer.
 
@@ -16,5 +20,5 @@ Release Procedure
 
 #. Make sure it is `available on PyPI <https://pypi.org/project/pluggy>`_.
 
-#. Merge ``release-X.Y.Z`` into ``master``, either manually or using GitHub's web interface.
+#. Merge the PR into ``master``, either manually or using GitHub's web interface.
 

changelog/README.rst

@@ -0,0 +1,32 @@
+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 with correct case and punctuation, for example::
+
+    Fix issue with non-ascii messages from the ``warnings`` module.
+
+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.
+* ``bugfix``: fixes a reported bug.
+* ``doc``: documentation improvement, like rewording an entire session or adding missing docs.
+* ``removal``: feature deprecation or removal.
+* ``vendor``: changes in packages vendored in pytest.
+* ``trivial``: fixing a small typo or internal change that might be noteworthy.
+
+So for example: ``123.feature.rst``, ``456.bugfix.rst``.
+
+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 install
+``towncrier`` and then run ``towncrier --draft``
+if you want to get a preview of how your change will look in the final release notes.

changelog/_template.rst

@@ -0,0 +1,40 @@
+{% for section in sections %}
+{% set underline = "-" %}
+{% if section %}
+{{section}}
+{{ underline * section|length }}{% set underline = "~" %}
+
+{% endif %}
+{% if sections[section] %}
+{% for category, val in definitions.items() if category in sections[section] %}
+
+{{ definitions[category]['name'] }}
+{{ underline * definitions[category]['name']|length }}
+
+{% if definitions[category]['showcontent'] %}
+{% for text, values in sections[section][category]|dictsort(by='value') %}
+{% set issue_joiner = joiner(', ') %}
+- {% for value in values|sort %}{{ issue_joiner() }}`{{ value }} <https://github.com/pytest-dev/pluggy/issues/{{ value[1:] }}>`_{% endfor %}: {{ text }}
+
+
+{% endfor %}
+{% else %}
+- {{ sections[section][category]['']|sort|join(', ') }}
+
+
+{% endif %}
+{% if sections[section][category]|length == 0 %}
+
+No significant changes.
+
+
+{% else %}
+{% endif %}
+{% endfor %}
+{% else %}
+
+No significant changes.
+
+
+{% endif %}
+{% endfor %}

pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = [
+  "setuptools",
+  "setuptools-scm",
+  "wheel",
+]
+
+[tool.towncrier]
+package = "pluggy"
+package_dir = "pluggy"
+filename = "CHANGELOG.rst"
+directory = "changelog/"
+template = "changelog/_template.rst"
+
+  [[tool.towncrier.type]]
+  directory = "removal"
+  name = "Deprecations and Removals"
+  showcontent = true
+
+  [[tool.towncrier.type]]
+  directory = "feature"
+  name = "Features"
+  showcontent = true
+
+  [[tool.towncrier.type]]
+  directory = "bugfix"
+  name = "Bug Fixes"
+  showcontent = true
+
+  [[tool.towncrier.type]]
+  directory = "vendor"
+  name = "Vendored Libraries"
+  showcontent = true
+
+  [[tool.towncrier.type]]
+  directory = "doc"
+  name = "Improved Documentation"
+  showcontent = true
+
+  [[tool.towncrier.type]]
+  directory = "trivial"
+  name = "Trivial/Internal Changes"
+  showcontent = true

scripts/release.py

@@ -0,0 +1,69 @@
+"""
+Release script.
+"""
+import argparse
+import sys
+from subprocess import check_call
+
+from colorama import init, Fore
+from git import Repo, Remote
+
+
+def create_branch(version):
+    """Create a fresh branch from upstream/master"""
+    repo = Repo.init('.')
+    if repo.is_dirty(untracked_files=True):
+        raise RuntimeError(f'Repository is dirty, please commit/stash your changes.')
+
+    branch_name = f"release-{version}"
+    print(f"{Fore.CYAN}Create {branch_name} branch from upstream master")
+    upstream = get_upstream(repo)
+    upstream.fetch()
+    release_branch = repo.create_head(branch_name, upstream.refs.master, force=True)
+    release_branch.checkout()
+    return repo
+
+
+def get_upstream(repo: Repo) -> Remote:
+    """Find upstream repository for pluggy on the remotes"""
+    for remote in repo.remotes:
+        for url in remote.urls:
+            if url.endswith("pytest-dev/pluggy.git"):
+                return remote
+    raise RuntimeError("could not find tox-dev/tox.git remote")
+
+
+def pre_release(version):
+    """Generates new docs, release announcements and creates a local tag."""
+    repo = create_branch(version)
+    changelog(version, write_out=True)
+    repo.index.add(['CHANGELOG.rst', 'changelog'])
+    repo.index.commit(f"Preparing release {version}")
+
+    print()
+    print(f"{Fore.GREEN}Please push your branch to your fork and open a PR.")
+
+
+def changelog(version, write_out=False):
+    if write_out:
+        addopts = []
+    else:
+        addopts = ["--draft"]
+    print(f"{Fore.CYAN}Generating CHANGELOG")
+    check_call(["towncrier", "--yes", "--version", version] + addopts)
+
+
+def main():
+    init(autoreset=True)
+    parser = argparse.ArgumentParser()
+    parser.add_argument("version", help="Release version")
+    options = parser.parse_args()
+    try:
+        pre_release(options.version)
+    except RuntimeError as e:
+        print(f'{Fore.RED}ERROR: {e}')
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tox.ini

@@ -42,3 +42,15 @@ filterwarnings =
 
 [flake8]
 max-line-length=99
+
+[testenv:release]
+decription = do a release, required posarg of the version number
+basepython = python3.6
+skipsdist = True
+usedevelop = True
+passenv = *
+deps =
+    colorama
+    gitpython
+    towncrier
+commands = python scripts/release.py {posargs}