Merge pull request #407 from twisted/406-release-docs

.readthedocs.yml

@@ -0,0 +1,18 @@
+version: 2
+
+sphinx:
+  # We want to fail as this is also our CI check for the docs.
+  fail_on_warning: True
+
+formats:
+  - pdf
+  - epub
+
+python:
+  version: "3.8"
+  system_packages: False
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev

MANIFEST.in

@@ -13,6 +13,7 @@ recursive-include src *.rst
 exclude bin
 exclude admin
 exclude src/towncrier/newsfragments
+exclude .readthedocs.yml
 
 recursive-exclude bin *
 recursive-exclude admin *

RELEASE.rst

@@ -1,96 +1,102 @@
 Releasing
 =========
 
-Summary
--------
-
-- Create a release branch in the main repository, not in a fork.
-- Create a commit for a release candidate inside the release branch.
-- Create a Pull Request for the release. The same branch and PR will be used for both the release candidates and  the final release.
-- Get an approving review.
-- Once approved, tag the last commit in the branch as a release candidate.
-- Push the tag.  This will trigger a build including the upload of artifacts to PyPI.
-- Notify the Twisted maillist allow a week for feedback before continuing.
-- Make sure that tickets exist for all raised concerns.  These tickets should be marked using the ``blocking`` label.
-- Address each issue by either concluding that it is not really a release blocker and removing the label or by fixing via a PR to the release branch.
-- Prepare a commit for a final release and push it to the release branch.
-- Get an approving review for the final release.
-- Tag the commit using the final release version. This will trigger the upload of artifacts to PyPI.
-
-
-Step-by-step
-------------
-
-.. note::
-
+..  note::
     Commands are written with Linux in mind and a ``venv`` located in ``venv/``.
     Adjust per your OS and virtual environment location.
     For example, on Windows with an environment in the directory ``myenv/`` the Python command would be ``myenv/scripts/python``.
 
-- Define the final release version you are preparing.
+Towncrier uses `CalVer <https://calver.org/>`_ of the form ``YY.MM.micro`` with the micro version just incrementing.
+
+Before the final release, a set of release candidates are released.
+
+
+Release candidate
+-----------------
 
-  - towncrier uses `CalVer <https://calver.org/>`_ of the form ``YY.MM.micro`` with the micro version just incrementing.
-  - Normalize the version according to `incremental <https://github.com/twisted/incremental/>`_.
+Create a release branch with a name of the form ``release-19.9.0`` starting from the main branch.
+The same branch is used for the release candidated and the final release.
+In the end, the release branch is merged into the main branch.
 
-    - This requires that ``towncrier[dev]`` extra is installed.
-    - ``venv/bin/python admin/canonicalize_version.py 19.09.00-rc1``
-    - Outputs ``19.9.0.rc1`` which is the form to be used.
+Update the version to the release candidate with the first being ``rc1`` (as opposed to 0).
+In ``src/towncrier/_version.py`` the version is set using ``incremental`` such as::
 
-- Create a release branch with a name of the form ``release-19.9.0`` starting from the ``master`` branch.
+    __version__ = Version('towncrier', 19, 9, 0, release_candidate=1)
 
-  - On the new release branch you will commit all tagged release candidate commits as well as the final tagged release commit.
+Run ``venv/bin/towncrier build --yes`` to generate the news release NEWS file.
+Commit and push to the primary repository, not a fork.
+It is important to not use a fork so that pushed tags end up in the primary repository,
+server provided secrets for publishing to PyPI are available, and maybe more.
 
-- Update the version to the release candidate with the first being ``rc1`` (as opposed to 0).
+Create a PR named in the form ``Release 19.9.0``.
+The same PR will be used for the release candidates and the final release.
 
-  - In ``src/towncrier/_version.py`` the version is set using ``incremental`` such as ``__version__ = Version('towncrier', 19, 9, 0, release_candidate=1)``
+Wait for the tests to be green.
+Start with the release candidates.
+Create a new release candidate using `GitHub New release UI <https://github.com/twisted/towncrier/releases/new>`_.
 
-- Run ``venv/bin/towncrier build --yes`` to build the the newsfragments into the release notes document and to automatically remove the newsfragment files.
+* *Choose a tag*: Type `19.9.0rc1` and select `Create new tag on publish.`
+* *Target*: Search for the release branch and select it.
+* *Title*: "Towncrier 19.9.0rc1".
+* Set the content based on the NEWS file.
+* Make sure to mark **This is a pre-release**.
+* Click `Publish release`
 
-- Commit and push to the primary repository, not a fork.
+This will trigger the PyPI release candidate.
 
-  - It is important to not use a fork so that pushed tags end up in the primary repository, server provided secrets for publishing to PyPI are available, and maybe more.
+Wait for the PyPI version to be published and then request a review for the PR from the ``twisted/twisted-contributors`` team.
 
-- If working on the first release candidate from this branch, create a PR named in the form ``Release 19.9.0``.
+In the PR request, you can give the link to the PyPI download and the documentation pages.
+The documentation link is also available as part of the standard Read The Docs PR checks.
 
-- Request a review and address raised concerns until receiving an approval.
+Notify the release candidate over IRC or Gitter to gain more attention.
+In the PR comments, you can also mention anyone who has asked for a release.
 
-- Tag that commit such as ``19.9.0.rc1`` and push the tag to the primary repository.
 
-  - This will result in another build which will publish to PyPI.
-  - Confirm the presence of the release on PyPI.
+Final release
+--------------
 
-- `Dismiss the approving review <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/dismissing-a-pull-request-review>`_.
+Once the PR is approved, you can trigger the final release.
 
-  - The review process will be reused for any subsequent release candidates, the final release, and the post-release tweaks so it must be cleared at each stage.
+Update the version to the final version.
+In ``src/towncrier/_version.py`` the version is set using ``incremental`` such as::
 
-- Notify the `Twisted-Python maillist <https://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python>`_ of the release to allow for feedback if a pre-release and just for notification if a final release.
+    __version__ = Version('towncrier', 19, 9, 0)
 
-- If another release candidate is required:
+Manually update the `NEWS.rst` file to include the final release version and date.
+Usually it will look like this::
 
-  - Submit PRs against the release branch to integrate the needed changes.  Any PRs could be cherry picks from the ``master`` branch if already resolved there, or direct PRs against the release branch that will be merged back into master at the completion of the release.
+    towncrier 19.9.0 (2019-09-29)
+    =============================
 
-  - Return to the step where the version is updated and increment the release candidate number.
+    No significant changes since the previous release candidate.
 
-- If ready for a final release, remove the release candidate indicator from the version.
+Commit and push the change.
+Wait for the tests to be green.
 
-  - Edit ``src/towncrier/_version.py`` such as ``__version__ = Version('towncrier', 19, 9, 0)`` to remove the release candidate indication.
+Trigger the final release using GitHub Release GUI.
 
-  - Manually update the NEWS.rst by removing the `.rcN` version and update the release date.
+Similar to the release candidate, with the difference:
 
-  - Disable the actual check for `tox -e check-newsfragment` so  that you will have a green test run.
+* tag will be named `19.9.0`
+* the target is the same branch
+* Title will be `towncrier 19.0.0`
+* Content can be the content of the final release and the release candidates.
+* Don't mark **This is a pre-release**.
+* Click `Publish release`
 
-  - Commit and push the changes to trigger the CI tests and make sure all are green.
+No need for another review request.
 
-  - Tag as ``19.9.0`` and push the tag to the primary repository.
+Update the version to the development version.
+In ``src/towncrier/_version.py`` the version is set using ``incremental`` such as::
 
-  - This will result in another build which will publish to PyPI for the final release.
+    __version__ = Version('towncrier', 19, 9, 1, dev=0)
 
-  - Confirm the presence of the release on PyPI.
 
-- If the final release has been completed, re-enable `tox -e check-newsfragment`.
+Commit and push the changes.
 
-- Increment the patch version by one and set to a development version.
+Merge the commit in the main branch.
 
-  - In ``src/towncrier/_version.py`` the version is set using ``incremental`` such as ``__version__ = Version('towncrier', 19, 9, 1, dev=0)``
+You can announce the release over IRC or Gitter.
 
-- Merge without waiting for an approving review.
+Done.

docs/conf.py

@@ -48,22 +48,6 @@
 copyright = "2017, Amber Brown"
 author = "Amber Brown"
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = "17.08"
-# The full version, including alpha/beta/rc tags.
-release = "17.08"
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
@@ -92,7 +76,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = []
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/configuration.rst

@@ -72,11 +72,12 @@ please notice that ``fragment_types`` must be empty or not provided.
 
 Each custom type (``[[tool.towncrier.type]]``) has the following
 mandatory keys:
- * ``directory``: The type of the fragment.
- * ``name``: The description of the fragment type, as it must be included
-   in the news file.
- * ``showcontent``: Whether if the fragment contents should be included in the
-   news file.
+
+* ``directory``: The type of the fragment.
+* ``name``: The description of the fragment type, as it must be included
+  in the news file.
+* ``showcontent``: Whether if the fragment contents should be included in the
+  news file.
 
 
 

docs/index.rst

@@ -6,3 +6,4 @@
    quickstart
    customisation/index
    configuration
+   release

docs/release.rst

@@ -0,0 +1,4 @@
+Release process
+===============
+
+.. include:: ../RELEASE.rst

setup.py

@@ -10,9 +10,7 @@
 
 setup(
     name="towncrier",
-    maintainer="Amber Brown",
-    maintainer_email="hawkowl@twistedmatrix.com",
-    url="https://github.com/hawkowl/towncrier",
+    url="https://github.com/twisted/towncrier",
     project_urls={
         "Documentation": "https://towncrier.readthedocs.io/",
         "Chat": "https://web.libera.chat/?channels=%23twisted",
@@ -47,7 +45,12 @@
         "setuptools",
         "tomli",
     ],
-    extras_require={"dev": ["packaging"]},
+    extras_require={
+        "dev": [
+            "packaging",
+            "sphinx >= 5",
+        ],
+    },
     package_dir={"": "src"},
     packages=find_packages("src"),
     license="MIT",

tox.ini

@@ -49,3 +49,11 @@ skip_install = true
 commands =
    # could be brought inside tox.ini after https://github.com/tox-dev/tox/issues/1571
    bash {toxinidir}/tox_build.sh
+
+[testenv:docs]
+extras = dev
+# I have no idea why the previous `extra = dev` doesn't install sphinx via tox.
+deps = sphinx >= 5
+commands =
+   # This tries to be as close as possible to the command used by Read The Docs.
+   python -m sphinx -T -E -W --keep-going -b html -d docs/_build/doctrees -D language=en docs docs/_build/html