Merge pull request #1927 from trentfridey/add-towncrier

Add towncrier for managing the changelog.

.github/pull_request_template.md

@@ -6,17 +6,12 @@ Thank you for contributing to QuTiP! Please make sure you have finished the foll
 You can use [pycodestyle](http://pycodestyle.pycqa.org/en/latest/index.html) to check your code automatically
 - [ ] Please add tests to cover your changes if applicable.
 - [ ] If the behavior of the code has changed or new feature has been added, please also update the documentation in the `doc` folder, and the [notebook](https://github.com/qutip/qutip-notebooks). Feel free to ask if you are not sure.
+- [ ] Include the changelog in a file named: `doc/changes/<PR number>.<type>` 'type' can be one of the following: feature, bugfix, doc, removal, misc, or deprecation (see [here](http://qutip.org/docs/latest/development/contributing.html#Changelog%20Generation) for more information).
 
 Delete this checklist after you have completed all the tasks. If you have not finished them all, you can also open a [Draft Pull Request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) to let the others know this on-going work and keep this checklist in the PR description.
 
 **Description**
 Describe here the proposed change.
 
 **Related issues or PRs**
-Please mention the related issues or PRs here. If the PR fixes an issue, use the keyword fix/fixes/fixed followed by the issue id, e.g. fix #1184
-
-**Changelog**
-Give a short description of the PR in a few words. This will be shown in the QuTiP change log after the PR gets merged.
-For example: 
-Fixed error checking for null matrix in essolve.
-Added option for specifying resolution in Bloch.save function.
+Please mention the related issues or PRs here. If the PR fixes an issue, use the keyword fix/fixes/fixed followed by the issue id, e.g. fix #1184

.github/workflows/tests.yml

@@ -181,6 +181,29 @@ jobs:
           COVERALLS_PARALLEL: true
         run: coveralls --service=github
 
+  towncrier-check:
+    name: Verify Towncrier entry added
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Install Towncrier
+        run: |
+          python -m pip install towncrier
+
+      - name: Verify Towncrier entry added
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+        run: |
+          # Fetch the pull request' base branch so towncrier will be able to
+          # compare the current branch with the base branch.
+          # Source: https://github.com/actions/checkout/#fetch-all-branches.
+          git fetch --no-tags origin +refs/heads/${BASE_BRANCH}:refs/remotes/origin/${BASE_BRANCH}
+          towncrier check --compare-with origin/${BASE_BRANCH}
+
   finalise:
     name: Finalise coverage reporting
     needs: cases

doc/changelog.rst

@@ -4,6 +4,8 @@
 Change Log
 **********
 
+.. towncrier release notes start
+
 Version 4.7.0 (April 13, 2022)
 ++++++++++++++++++++++++++++++
 

doc/changes/.gitignore

@@ -0,0 +1,2 @@
+# This ensures that the folder persists after the removal of the files in it in a new version release.
+!.gitignore

doc/changes/1927.doc

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

doc/development/contributing.rst

@@ -132,6 +132,20 @@ You can also use the ``-k`` selector to only run tests whose names include a par
 
 to run the tests of :meth:`Qobj.expm`.
 
+Changelog Generation
+--------------------
+
+We use ``towncrier`` for tracking changes and generating a changelog.
+When making a pull request, we require that you add a towncrier entry along with the code changes.
+You should create a file named ``<PR number>.<change type>`` in the ``doc/changes`` directory, where the PR number should be substituted for ``<PR number>``, and ``<change type>`` is either ``feature``, ``bugfix``, ``doc``, ``removal``, ``misc``, or ``deprecation``,
+depending on the type of change included in the PR.
+
+You can also create this file by installing ``towncrier`` and running 
+
+   towncrier create <PR number>.<change type>
+
+Running this will create a file in the ``doc/changes`` directory with a filename corresponding to the argument you passed to ``towncrier create``.
+In this file, you should add a short description of the changes that the PR introduces.
 
 .. _contributing-docs:
 

doc/development/release_distribution.rst

@@ -54,11 +54,12 @@ Updating the Changelog
 This needs to be done no matter what type of release is being made.
 
 #. Create a new branch to use to make a pull request.
-#. Write the changelog for this version in ``doc/changelog.rst``.
-   Look at recent entries in that file to get a feel for the style.
-   In general, the format is one or two paragraphs written in regular prose describing the major new features of the version, and anything that needs special attention.
-   After that, in suitable headings, list all the changes and who made them.
-   Headings you may want to have include "Features", "Improvements", "Bug Fixes", "Deprecations", "Removals" and "Developer Changes", but feel free to use anything sensible.
+#. Update the changelog using ``towncrier``:
+
+   towncrier build --version=<version-number>
+
+Where ``<version-number>`` is the expected version number of the release
+
 #. Make a pull request on the main ``qutip/qutip`` repository with this changelog, and get other members of the admin team to approve it.
 #. Merge this into ``master``.
 

pyproject.toml

@@ -22,3 +22,31 @@ build-frontend = "pip"
 select = "cp3?-*"
 manylinux-x86_64-image = "manylinux2010"
 manylinux-i686-image = "manylinux2010"
+
+[tool.towncrier]
+directory = "doc/changes"
+filename = "doc/changelog.rst"
+[[tool.towncrier.type]]
+directory = "deprecation"
+name = "Deprecations"
+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 = "removal"
+name = "Removals"
+showcontent = true
+[[tool.towncrier.type]]
+directory = "doc"
+name = "Documentation"
+showcontent = true
+[[tool.towncrier.type]]
+directory = "misc"
+name = "Miscellaneous"
+showcontent = true