docs: migrate to scriv to manage changelog

Changelog management was starting to be a hassle:

- there were conflicts every time a PR was merged
- there were conflicts every time we merged the nightly branch in the new
  release branch, or vice versa.

Now, all changelog entries are stored as separate files in changelog.d,
including nightly. Nightly entries will be collected for every major release.

CHANGELOG-nightly.md

@@ -1,10 +0,0 @@
-# Changelog (nightly branch)
-
-<!--
-his changelog is for tracking changes made to the nightly branch (see:
-https://docs.tutor.overhang.io/tutorials/nightly.html). The format of this file is identical
-to the CHANGELOG.md file, except that there are not releases or "Unrelased sections. Entries
-will be backported to the master branch at every major release.
-When backporting changes to master, we should keep only the entries that correspond to user-
-facing changes.
--->

CHANGELOG.md

@@ -1,21 +1,25 @@
 # Changelog
 
+This file includes a history of past releases. Changes that were not yet added to a release are in the [changelog.d/](./changelog.d) folder.
+
 <!--
-Every user-facing change should have an entry in this changelog. Please respect the following instructions:
-- Add your changes right below the "Unreleased" section title. If there are other unreleased changes,
-  add your own on top of them, as the first line in that section.
-- Indicate breaking changes by prepending an explosion 💥 character.
-- You may optionally append "(by <author>)" at the end of the line, where "<author>" is either one (just one)
-  of your GitHub username, real name or affiliated organization. These affiliations will be displayed in
-  he release notes for every release.
-- If you need to create a new release, create a separate commit just for that. It is important to respect these
-  instructions, because git commits are used to generate release notes:
-    - Add a "## vX.Y.Z (year-month-day)" line just below "## Unreleased", such that the new changes are now listed as part of release.
-    - The title of the commit should be the same as the section title: "vX.Y.Z (year-month-day)".
-    - The commit message should be copy-pasted from the release section.
-    - Have a look at other release commits for reference.
+⚠️ DO NOT ADD YOUR CHANGES TO THIS FILE! (unless you want to modify existing changelog entries in this file)
+Changelog entries are managed by scriv. After you have made some changes to Tutor, create a changelog entry with:
+
+    make changelog-entry
+
+Edit and commit the newly-created file in changelog.d.
+
+If you need to create a new release, create a separate commit just for that. It is important to respect these
+instructions, because git commits are used to generate release notes:
+  - Collect changelog entries with `make changelog`
+  - The title of the commit should be the same as the CHANGELOG.md file section title: "vX.Y.Z (year-month-day)".
+  - The commit message should be copy-pasted from the release section.
+  - Have a look at other release commits for reference.
 -->
 
+<!-- scriv-insert-here -->
+
 ## Unreleased
 
 - [Improvement] Enable CORS by default for both LMS and CMS by moving those settings to the `common_all` partial. (by @arbrandes)

Makefile

@@ -83,6 +83,13 @@ coverage-browse-report: coverage-html ## Open the HTML report in the browser
 bundle: ## Bundle the tutor package in a single "dist/tutor" executable
 	pyinstaller tutor.spec
 
+
+changelog-entry: ## Create a new changelog entry
+	scriv create
+
+changelog: ## Collect changelog entries in the CHANGELOG.md file
+	scriv collect
+
 release: test release-unsafe ## Create a release tag and push it to origin
 release-unsafe:
 	$(MAKE) release-tag release-push TAG=v$(shell make version)

changelog.d/scriv.ini

@@ -0,0 +1,7 @@
+[scriv]
+version = literal: tutor/__about__.py: __version__
+categories =
+format = md
+md_header_level = 2
+new_fragment_template = file: scriv/new_fragment.${config:format}.j2
+entry_title_template = file: scriv/entry_title.${config:format}.j2

changelog.d/scriv/entry_title.md.j2

@@ -0,0 +1 @@
+{% if version %}v{{ version }} {% endif %}({{ date.strftime('%Y-%m-%d') }})

changelog.d/scriv/new_fragment.md.j2

@@ -0,0 +1,11 @@
+<!--
+Create a changelog entry for every new user-facing change. Please respect the following instructions:
+- Indicate breaking changes by prepending an explosion 💥 character.
+- Prefix your changes with either [Bugfix], [Improvement], [Feature], [Security], [Deprecation].
+- You may optionally append "(by @<author>)" at the end of the line, where "<author>" is either one (just one)
+  of your GitHub username, real name or affiliated organization. These affiliations will be displayed in
+  the release notes for every release.
+-->
+
+<!-- - 💥[Feature] Foobarize the blorginator. This breaks plugins by renaming the `FOO_DO` filter to `BAR_DO`. (by @regisb) -->
+<!-- - [Improvement] This is a non-breaking change. Life is good. (by @billgates) -->

docs/tutor.rst

@@ -69,9 +69,9 @@ Releasing a new version
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 - Bump the ``__version__`` value in ``tutor/__about__.py``. (see :ref:`versioning` below)
-- Replace "Unreleased" with the version name and date in CHANGELOG.md.
+- Collect changelog entries with ``make changelog``.
 - Create a commit with the version changelog.
-- Run ``make release``: this will push to the default repo/branch for the current branch.
+- Run ``make release``: this will create a tag and push to the default repo/branch for the current branch.
 
 .. _versioning:
 
@@ -102,12 +102,7 @@ Third-party contributions to Tutor and its plugins are more than welcome! Just m
 - Outside of obvious bugs, contributions should be discussed first in the `official Open edX forum <https://discuss.openedx.org>`__.
 - Once we agree on a high-level solution, you should open a pull request on the `Tutor repository <https://github.com/overhangio/tutor/pulls>`__ or the corresponding plugin.
 - Make sure that all tests pass by running ``make test`` (see above).
-- If your PR is in the Tutor core repository, add an item to the CHANGELOG file, in the "Unreleased" section. Use the same format as the other items::
-
-    - [TYPE] DESCRIPTION
-
-Where "TYPE" is either "Bugfix", "Improvement", "Feature" or "Security". You should add an explosion emoji ("💥") before "[TYPE]" if you are making a breaking change.
-
+- If your PR is in the Tutor core repository, add a changelog entry by running ``make changelog-entry``. Edit the new file and follow the formatting instructions that it contains.
 - Write a good Git commit title and message: explain why you are making this change, what problem you are solving and which solution you adopted. Link to the relevant conversation topics in the forums and describe your use case. We *love* long, verbose descriptions :) As for the title, `conventional commits <https://www.conventionalcommits.org>`__ are preferred. Check the repo history!
 
 Happy hacking! ☘️

docs/tutorials/nightly.rst

@@ -61,4 +61,4 @@ Making changes to Tutor Nightly
 In general pull requests should be open on the "master" branch of Tutor: the "master" branch is automatically merged on the "nightly" branch at every commit, such that changes made to Tutor releases find their way to Tutor Nightly as soon as they are merged. However, sometimes you want to make changes to Tutor Nightly exclusively, and not to the Tutor releases. This might be the case for instance when upgrading the running version of a third-party service (for instance: Elasticsearch, MySQL), or when the master branch requires specific changes. In that case, you should follow the instructions from the :ref:`contributing` section of the docs, with the following differences:
 
 - Open your pull request on top of the "nightly" branch instead of "master".
-- Add a description of your changes to CHANGELOG-nightly.md instead of CHANGELOG.md
+- Add a description of your changes to by creating a changelog entry with `make changelog-entry`, as in the master branch.

requirements/dev.in

@@ -1,10 +1,11 @@
 -r base.txt
 black
+coverage
 pip-tools
 pylint
 pyinstaller
+scriv
 twine
-coverage
 
 # doc requirement is lagging behind
 # https://github.com/readthedocs/sphinx_rtd_theme/issues/1323

requirements/dev.txt

@@ -10,6 +10,8 @@ appdirs==1.4.4
     # via -r requirements/base.txt
 astroid==2.12.13
     # via pylint
+attrs==22.1.0
+    # via scriv
 black==22.10.0
     # via -r requirements/dev.in
 bleach==5.0.1
@@ -35,7 +37,11 @@ click==8.1.3
     # via
     #   -r requirements/base.txt
     #   black
+    #   click-log
     #   pip-tools
+    #   scriv
+click-log==0.4.0
+    # via scriv
 commonmark==0.9.1
     # via rich
 coverage==6.5.0
@@ -69,7 +75,9 @@ jeepney==0.8.0
     #   keyring
     #   secretstorage
 jinja2==3.1.2
-    # via -r requirements/base.txt
+    # via
+    #   -r requirements/base.txt
+    #   scriv
 keyring==23.11.0
     # via twine
 kubernetes==25.3.0
@@ -150,6 +158,7 @@ requests==2.28.1
     #   kubernetes
     #   requests-oauthlib
     #   requests-toolbelt
+    #   scriv
     #   twine
 requests-oauthlib==1.3.1
     # via
@@ -165,6 +174,8 @@ rsa==4.9
     # via
     #   -r requirements/base.txt
     #   google-auth
+scriv==0.17.0
+    # via -r requirements/dev.in
 secretstorage==3.3.3
     # via keyring
 six==1.16.0