add towncrier to manage changelog

.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.**
 <!-- Please review the [test documentation](https://docs.saltstack.com/en/master/topics/tutorials/writing_tests.html) for details on how to implement tests into Salt's test suite. -->
 - [ ] Docs
-- [ ] Changelog
+- [ ] Changelog - https://docs.saltstack.com/en/latest/topics/development/changelog.html
 - [ ] Tests written/updated
 
 ### Commits signed with GPG?

.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

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
 

changelog/55836.added

@@ -0,0 +1 @@
+Add towncrier tool to the Salt project to help manage CHANGELOG.md file.

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=<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 ``<issue #>.<type>``.
+
+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/

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)

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

requirements/static/changelog.in

@@ -0,0 +1 @@
+towncrier

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

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

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