From c886b72ae74b3fe2f828fdab1e9c662aa625bd8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9gis=20Behmo?= Date: Mon, 21 Nov 2022 16:35:14 +0100 Subject: [PATCH] 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 | 10 ---------- CHANGELOG.md | 30 ++++++++++++++++------------ Makefile | 7 +++++++ changelog.d/scriv.ini | 7 +++++++ changelog.d/scriv/entry_title.md.j2 | 1 + changelog.d/scriv/new_fragment.md.j2 | 11 ++++++++++ docs/tutor.rst | 11 +++------- docs/tutorials/nightly.rst | 2 +- requirements/dev.in | 3 ++- requirements/dev.txt | 13 +++++++++++- 10 files changed, 61 insertions(+), 34 deletions(-) delete mode 100644 CHANGELOG-nightly.md create mode 100644 changelog.d/scriv.ini create mode 100644 changelog.d/scriv/entry_title.md.j2 create mode 100644 changelog.d/scriv/new_fragment.md.j2 diff --git a/CHANGELOG-nightly.md b/CHANGELOG-nightly.md deleted file mode 100644 index a5553a7..0000000 --- a/CHANGELOG-nightly.md +++ /dev/null @@ -1,10 +0,0 @@ -# Changelog (nightly branch) - - diff --git a/CHANGELOG.md b/CHANGELOG.md index 59fb3cf..72e17ac 100644 --- a/CHANGELOG.md +++ b/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. + + + ## Unreleased - [Improvement] Enable CORS by default for both LMS and CMS by moving those settings to the `common_all` partial. (by @arbrandes) diff --git a/Makefile b/Makefile index b0d5953..844548c 100644 --- a/Makefile +++ b/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) diff --git a/changelog.d/scriv.ini b/changelog.d/scriv.ini new file mode 100644 index 0000000..9236140 --- /dev/null +++ b/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 diff --git a/changelog.d/scriv/entry_title.md.j2 b/changelog.d/scriv/entry_title.md.j2 new file mode 100644 index 0000000..7afe894 --- /dev/null +++ b/changelog.d/scriv/entry_title.md.j2 @@ -0,0 +1 @@ +{% if version %}v{{ version }} {% endif %}({{ date.strftime('%Y-%m-%d') }}) diff --git a/changelog.d/scriv/new_fragment.md.j2 b/changelog.d/scriv/new_fragment.md.j2 new file mode 100644 index 0000000..78988a4 --- /dev/null +++ b/changelog.d/scriv/new_fragment.md.j2 @@ -0,0 +1,11 @@ + + + + diff --git a/docs/tutor.rst b/docs/tutor.rst index 04e87e3..ef9d872 100644 --- a/docs/tutor.rst +++ b/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 `__. - Once we agree on a high-level solution, you should open a pull request on the `Tutor repository `__ 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 `__ are preferred. Check the repo history! Happy hacking! ☘️ diff --git a/docs/tutorials/nightly.rst b/docs/tutorials/nightly.rst index d963518..5f0acf2 100644 --- a/docs/tutorials/nightly.rst +++ b/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. diff --git a/requirements/dev.in b/requirements/dev.in index 6540e89..4c1100d 100644 --- a/requirements/dev.in +++ b/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 diff --git a/requirements/dev.txt b/requirements/dev.txt index 80048a8..5d30588 100644 --- a/requirements/dev.txt +++ b/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