From 57d160cc606f405f7929cde2bc7dde17e575a1c4 Mon Sep 17 00:00:00 2001 From: ch3ll Date: Tue, 14 Apr 2020 18:37:33 -0400 Subject: [PATCH] add towncrier to manage changelog --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .pre-commit-config.yaml | 27 ++++++++ CHANGELOG.md | 4 +- changelog/55836.added | 1 + doc/topics/development/changelog.rst | 87 +++++++++++++++++++++++++ noxfile.py | 23 +++++++ pyproject.toml | 31 +++++++++ requirements/static/changelog.in | 1 + requirements/static/py3.5/changelog.txt | 12 ++++ requirements/static/py3.6/changelog.txt | 12 ++++ requirements/static/py3.7/changelog.txt | 12 ++++ 11 files changed, 210 insertions(+), 2 deletions(-) create mode 100644 changelog/55836.added create mode 100644 doc/topics/development/changelog.rst create mode 100644 requirements/static/changelog.in create mode 100644 requirements/static/py3.5/changelog.txt create mode 100644 requirements/static/py3.6/changelog.txt create mode 100644 requirements/static/py3.7/changelog.txt diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index dbfed2617ac..d05ff8cd077 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -13,7 +13,7 @@ Remove this section if not relevant **[NOTICE] Bug fixes or features added to Salt require tests.** - [ ] Docs -- [ ] Changelog +- [ ] Changelog - https://docs.saltstack.com/en/latest/topics/development/changelog.html - [ ] Tests written/updated ### Commits signed with GPG? diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index db86537ce09..22e31a5d96f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -67,6 +67,15 @@ repos: - --py-version=3.5 - --platform=linux + - id: pip-tools-compile + alias: compile-changelog-requirements + name: Changelog Py3.5 Requirements + files: ^requirements/static/changelog\.in$ + args: + - -v + - --py-version=3.5 + - --platform=linux + - id: pip-tools-compile alias: compile-linux-crypto-py3.5-requirements name: Linux Py3.5 Crypto Requirements @@ -166,6 +175,15 @@ repos: - --py-version=3.6 - --platform=linux + - id: pip-tools-compile + alias: compile-changelog-requirements + name: Changelog Py3.6 Requirements + files: ^requirements/static/changelog\.in$ + args: + - -v + - --py-version=3.6 + - --platform=linux + - id: pip-tools-compile alias: compile-linux-crypto-py3.6-requirements name: Linux Py3.6 Crypto Requirements @@ -265,6 +283,15 @@ repos: - --py-version=3.7 - --platform=linux + - id: pip-tools-compile + alias: compile-changelog-requirements + name: Changelog Py3.7 Requirements + files: ^requirements/static/changelog\.in$ + args: + - -v + - --py-version=3.7 + - --platform=linux + - id: pip-tools-compile alias: compile-linux-crypto-py3.7-requirements name: Linux Py3.7 Crypto Requirements diff --git a/CHANGELOG.md b/CHANGELOG.md index b09e43ad280..218b0abf073 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,3 @@ -# Changelog All notable changes to Salt will be documented in this file. This changelog follows [keepachangelog](https://keepachangelog.com/en/1.0.0/) format, and is intended for human consumption. @@ -7,6 +6,9 @@ This project versioning is _similar_ to [Semantic Versioning](https://semver.org Versions are `MAJOR.PATCH`. ## 3001 - Sodium +# Changelog + +### 3000.1 ### Removed diff --git a/changelog/55836.added b/changelog/55836.added new file mode 100644 index 00000000000..5bec52a40aa --- /dev/null +++ b/changelog/55836.added @@ -0,0 +1 @@ +Add towncrier tool to the Salt project to help manage CHANGELOG.md file. diff --git a/doc/topics/development/changelog.rst b/doc/topics/development/changelog.rst new file mode 100644 index 00000000000..c47deaa956a --- /dev/null +++ b/doc/topics/development/changelog.rst @@ -0,0 +1,87 @@ +.. _changelog: + +========= +Changelog +========= + +With the addition of `SEP 01`_ the `keepachangelog`_ format was introduced into +our CHANGELOG.md file. The Salt project is using the `towncrier`_ tool to manage +the Changelog.md file. The reason this tool was added to manage the changelog +was because we were previously managing the file manually and it would cause +many merge conflicts. This tool allows us to add changelog entries into separate +files and before a release we simply need to run ``towncrier --version=`` +for it to compile the changelog correctly. + + +.. _add-changelog: + +How do I add a changelog entry +------------------------------ + +To add a changelog entry you will need to add a file in the `changelog` directory. +The file name should follow the syntax ``.``. + +The types are in alignment with keepachangelog: + + removed: + any features that have been removed + + deprecated: + any features that will soon be removed + + changed: + any changes in current existing features + + fixed: + any bug fixes + + added: + any new features added + +For example if you are fixing a bug for issue number #1234 your filename would +look like this: changelog/1234.fixed. The contents of the file should contain +a summary of what you are fixing. + +This does require that an issue be linked to all of the types above. + +.. _generate-changelog: + +How to generate the changelog +----------------------------- + +This step is only used when we need to generate the changelog right before releasing. +You should NOT run towncrier on your PR, unless you are preparing the final PR +to update the changelog before a release. + +You can run the `towncrier` tool directly or you can use nox to help run the command +and ensure towncrier is installed in a virtual environment. The instructions below +will detail both approaches. + +If you want to see what output towncrier will produce before generating the change log +you can run towncrier in draft mode: + +.. code-block:: bash + + towncrier --draft --version=3001 + +.. code-block:: bash + + nox -e 'changelog(draft=True)' -- 3000.1 + +Version will need to be set to whichever version we are about to release. Once you are +confident the draft output looks correct you can now generate the changelog by running: + +.. code-block:: bash + + towncrier --version=3001 + +.. code-block:: bash + + nox -e 'changelog(draft=False)' -- 3000.1 + +After this is run towncrier will automatically remove all the files in the changelog directory. + + +.. _`SEP 01`: https://github.com/saltstack/salt-enhancement-proposals/pull/2 +.. _`keepachangelog`: https://keepachangelog.com/en/1.0.0/ +.. _`towncrier`: https://pypi.org/project/towncrier/ diff --git a/noxfile.py b/noxfile.py index faa06d4c38b..02be17d03a0 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1129,3 +1129,26 @@ def docs_man(session, compress, update): if compress: session.run("tar", "-cJvf", "man-archive.tar.xz", "_build/man", external=True) os.chdir("..") + + +@nox.session(name="changelog", python="3") +@nox.parametrize("draft", [False, True]) +def changelog(session, draft): + """ + Generate salt's changelog + """ + + pydir = _get_pydir(session) + requirements_file = "requirements/static/changelog.in" + distro_constraints = [ + "requirements/static/{}/changelog.txt".format(_get_pydir(session)) + ] + install_command = ["--progress-bar=off", "-r", requirements_file] + for distro_constraint in distro_constraints: + install_command.extend(["--constraint", distro_constraint]) + session.install(*install_command, silent=PIP_INSTALL_SILENT) + + town_cmd = ["towncrier", "--version={0}".format(session.posargs[0])] + if draft: + town_cmd.append("--draft") + session.run(*town_cmd) diff --git a/pyproject.toml b/pyproject.toml index afc8a6fae3f..9969e02d0e9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -16,3 +16,34 @@ line_length = 88 ensure_newline_before_comments=true skip="salt/ext,tests/kitchen,templates" +[tool.towncrier] + package = "salt" + package_dir = "salt" + filename = "CHANGELOG.md" + directory = "changelog/" + start_string = "# Changelog\n" + + [[tool.towncrier.type]] + directory = "removed" + name = "Removed" + showcontent = true + + [[tool.towncrier.type]] + directory = "deprecated" + name = "Deprecated" + showcontent = true + + [[tool.towncrier.type]] + directory = "changed" + name = "Changed" + showcontent = true + + [[tool.towncrier.type]] + directory = "fixed" + name = "Fixed" + showcontent = true + + [[tool.towncrier.type]] + directory = "added" + name = "Added" + showcontent = true diff --git a/requirements/static/changelog.in b/requirements/static/changelog.in new file mode 100644 index 00000000000..0d2d2d7db84 --- /dev/null +++ b/requirements/static/changelog.in @@ -0,0 +1 @@ +towncrier diff --git a/requirements/static/py3.5/changelog.txt b/requirements/static/py3.5/changelog.txt new file mode 100644 index 00000000000..ecef1b39a0e --- /dev/null +++ b/requirements/static/py3.5/changelog.txt @@ -0,0 +1,12 @@ +# +# This file is autogenerated by pip-compile +# To update, run: +# +# pip-compile -o requirements/static/py3.5/changelog.txt -v requirements/static/changelog.in +# +click==7.1.1 # via towncrier +incremental==17.5.0 # via towncrier +jinja2==2.11.2 # via towncrier +markupsafe==1.1.1 # via jinja2 +toml==0.10.0 # via towncrier +towncrier==19.2.0 diff --git a/requirements/static/py3.6/changelog.txt b/requirements/static/py3.6/changelog.txt new file mode 100644 index 00000000000..dd0c469a336 --- /dev/null +++ b/requirements/static/py3.6/changelog.txt @@ -0,0 +1,12 @@ +# +# This file is autogenerated by pip-compile +# To update, run: +# +# pip-compile -o requirements/static/py3.6/changelog.txt -v requirements/static/changelog.in +# +click==7.1.1 # via towncrier +incremental==17.5.0 # via towncrier +jinja2==2.11.2 # via towncrier +markupsafe==1.1.1 # via jinja2 +toml==0.10.0 # via towncrier +towncrier==19.2.0 diff --git a/requirements/static/py3.7/changelog.txt b/requirements/static/py3.7/changelog.txt new file mode 100644 index 00000000000..b6a06719840 --- /dev/null +++ b/requirements/static/py3.7/changelog.txt @@ -0,0 +1,12 @@ +# +# This file is autogenerated by pip-compile +# To update, run: +# +# pip-compile -o requirements/static/py3.7/changelog.txt -v requirements/static/changelog.in +# +click==7.1.1 # via towncrier +incremental==17.5.0 # via towncrier +jinja2==2.11.2 # via towncrier +markupsafe==1.1.1 # via jinja2 +toml==0.10.0 # via towncrier +towncrier==19.2.0