[3006.x] Use jinja templating for the release notes

.github/workflows/nightly.yml

@@ -318,8 +318,13 @@ jobs:
         shell: bash
         if: ${{ startsWith(github.event.ref, 'refs/tags') == false }}
         run: |
-          tools changelog update-release-notes --draft
-          tools changelog update-release-notes
+          if [ "${{ contains(fromJSON('["master"]'), github.ref_name) }}" == "true" ]; then
+              tools changelog update-release-notes --draft --next-release
+              tools changelog update-release-notes --next-release
+          else
+              tools changelog update-release-notes --draft
+              tools changelog update-release-notes
+          fi
 
       - name: Generate MAN Pages
         shell: bash

.github/workflows/templates/ci.yml.jinja

@@ -116,8 +116,18 @@ on:
         shell: bash
         if: ${{ startsWith(github.event.ref, 'refs/tags') == false }}
         run: |
+          <%- if gh_environment == 'nightly' %>
+          if [ "${{ contains(fromJSON('["master"]'), github.ref_name) }}" == "true" ]; then
+              tools changelog update-release-notes --draft <%- if prepare_actual_release %> --release <%- endif %> --next-release
+              tools changelog update-release-notes <%- if prepare_actual_release %> --release <%- endif %> --next-release
+          else
+              tools changelog update-release-notes --draft <%- if prepare_actual_release %> --release <%- endif %>
+              tools changelog update-release-notes <%- if prepare_actual_release %> --release <%- endif %>
+          fi
+          <%- else %>
           tools changelog update-release-notes --draft <%- if prepare_actual_release %> --release <%- endif %>
           tools changelog update-release-notes <%- if prepare_actual_release %> --release <%- endif %>
+          <%- endif %>
 
       - name: Generate MAN Pages
         shell: bash

changelog/64023.added.md

@@ -0,0 +1 @@
+Add --next-release argument to salt/version.py, which prints the next upcoming release.

doc/topics/development/releasenotes.rst

@@ -0,0 +1,71 @@
+.. _releasenotes:
+
+=============
+Release Notes
+=============
+
+You can edit the release notes to highlight a new feature being added
+to a given release. The release notes are templatized with Jinja and
+are generated at release time.
+
+
+.. _edit-release-note:
+
+How do I edit the release notes
+-------------------------------
+
+To edit the release notes you need to look in doc/topics/releases/templates
+for your given release and edit the template. Do not edit the release note
+files in doc/topics/releases/, as this will be written over with the content
+in the template file. For example, if you want to add content to the 3006.0
+release notes you would edit the doc/topics/releases/templates/3006.0.md.template
+file. Do not edit the changelog portion of the template file, since that is
+auto generated with the content generated for the changelog for each release.
+
+
+How to generate the release notes
+---------------------------------
+
+This step is only used when we need to generate the release notes before releasing.
+You should NOT need to run these steps as they are ran in the pipeline, but this
+is documented so you can test your changes to the release notes template.
+
+To generate the release notes requires the `tools` command. The instructions below
+will detail how to install and use `tools`.
+
+
+Installing `tools`
+..................
+
+.. code-block: bash
+
+    python -m pip install -r requirements/static/ci/py3.10/tools.txt
+
+
+To view the output the release notes will produce before generating them
+you can run `tools` in draft mode:
+
+.. code-block:: bash
+
+    tools changelog update-release-notes --draft
+
+To generate the release notes just remove the `--draft` argument:
+
+.. code-block:: bash
+
+    tools changelog update-release-notes
+
+
+To specify a specific Salt version you add that version as an argument:
+
+.. code-block:: bash
+
+    tools changelog update-release-notes 3006.0
+
+
+To only generate the template for a new release
+
+
+.. code-block:: bash
+
+    tools changelog update-release-notes --template-only

doc/topics/releases/templates/3006.0.md.template

@@ -0,0 +1,68 @@
+(release-3006.0)=
+# Salt 3006.0 release notes{{ unreleased }}
+{{ warning }}
+
+<!--
+Add relase specific details below
+-->
+
+## Onedir packaging
+
+Going forward from the 3006.0 release, the Salt Project will only provide onedir
+packages to install or upgrade Salt. The classic, non-onedir packages will not
+be provided for supported operating systems. See [Upgrade to onedir](https://docs.saltproject.io/salt/install-guide/en/latest/topics/upgrade-to-onedir.html)
+in the [Salt Install Guide](https://docs.saltproject.io/salt/install-guide/en/latest) for information about upgrading from the classic packages to the onedir
+packages.
+
+
+## Dropping support for Python 3.5 and 3.6
+
+Python 3.5 and 3.6 will no longer be supported by Salt since they
+are end of life. Going forward our policy will be to align with Python's
+supported versions. See [Salt support for Python versions](https://docs.saltproject.io/salt/install-guide/en/latest/topics/salt-python-version-support.html)
+for more information.
+
+
+## All salt-api functionality disabled by default
+
+All netapi clients, which provide the functionality to ``salt-api``, will now
+be disabled by default as a security precaution. If you use ``salt-api``, you
+must add the new ``netapi_enable_clients`` option to your salt master config.
+This is a breaking change and the ``salt-api`` will not function without this
+new configuration option. See [Enabling netapi client interfaces](https://docs.saltproject.io/en/3006.0/topics/netapi/netapi-enable-clients.html#netapi-enable-clients)
+for more information.
+
+
+## How do I migrate to the onedir packages?
+
+The migration path from the classic, non-onedir packages to the onedir packages
+will include:
+
+* Repo File: You need to update your repo file to point to the new repo paths
+  for your platform. After the repo file is updated, upgrade your Salt packages.
+* Pip packages: You need to ensure any 3rd party pip packages are installed in
+  the correct onedir path. This can be accomplished in two ways:
+
+  * ``salt-pip install <package name>``
+  * Using the ``pip.installed`` Salt state.
+
+To install python packages into the system python environment, user's must now
+provide the ``pip_bin`` or ``bin_env`` to the pip state module.
+
+For example:
+
+```yaml
+lib-foo:
+  pip.installed:
+    - pip_bin: /usr/bin/pip3
+lib-bar:
+  pip.installed:
+    - bin_env: /usr/bin/python3
+```
+
+<!--
+Do not edit the changelog below.
+This is auto generated
+-->
+## Changelog
+{{ changelog }}

doc/topics/releases/templates/3007.0.md.template

@@ -0,0 +1,15 @@
+(release-3007.0)=
+# Salt 3007.0 release notes{{ unreleased }}
+{{ warning }}
+
+<!--
+Add release specific details below
+-->
+
+
+<!--
+Do not edit the changelog below.
+This is auto generated
+-->
+## Changelog
+{{ changelog }}

salt/version.py

@@ -1,6 +1,7 @@
 """
 Set up the version of Salt
 """
+import argparse
 import operator
 import os
 import platform
@@ -921,5 +922,17 @@ def versions_report(include_salt_cloud=False, include_extensions=True):
     yield from info
 
 
+def _parser():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--next-release", help="Return the next release", action="store_true"
+    )
+    return parser.parse_args()
+
+
 if __name__ == "__main__":
-    print(__version__)
+    args = _parser()
+    if args.next_release:
+        print(__saltstack_version__.next_release())
+    else:
+        print(__version__)

tools/changelog.py

@@ -12,6 +12,7 @@
 import sys
 import textwrap
 
+from jinja2 import Environment, FileSystemLoader
 from ptscripts import Context, command_group
 
 from tools.utils import REPO_ROOT, Version
@@ -174,8 +175,11 @@ def _get_pkg_changelog_contents(ctx: Context, version: Version):
     return changes
 
 
-def _get_salt_version(ctx):
-    ret = ctx.run("python3", "salt/version.py", capture=True, check=False)
+def _get_salt_version(ctx, next_release=False):
+    args = []
+    if next_release:
+        args.append("--next-release")
+    ret = ctx.run("python3", "salt/version.py", *args, capture=True, check=False)
     if ret.returncode:
         ctx.error(ret.stderr.decode())
         ctx.exit(1)
@@ -295,52 +299,105 @@ def update_deb(ctx: Context, salt_version: Version, draft: bool = False):
         "release": {
             "help": "Update for an actual release and not just a temporary CI build.",
         },
+        "template_only": {
+            "help": "Only generate a template file.",
+        },
+        "next_release": {
+            "help": "Generate release notes for the next upcoming release.",
+        },
     },
 )
 def update_release_notes(
-    ctx: Context, salt_version: Version, draft: bool = False, release: bool = False
+    ctx: Context,
+    salt_version: Version,
+    draft: bool = False,
+    release: bool = False,
+    template_only: bool = False,
+    next_release: bool = False,
 ):
     if salt_version is None:
-        salt_version = _get_salt_version(ctx)
+        salt_version = _get_salt_version(ctx, next_release=next_release)
     changes = _get_changelog_contents(ctx, salt_version)
     changes = "\n".join(changes.split("\n")[2:])
     if salt_version.local:
         # This is a dev release, let's pick up the latest changelog file
         versions = {}
         for fpath in pathlib.Path("doc/topics/releases").glob("*.md"):
             versions[(Version(fpath.stem))] = fpath
-        release_notes_path = versions[sorted(versions)[-1]]
+        latest_version = sorted(versions)[-1]
+        release_notes_path = versions[latest_version]
+        version = ".".join(str(part) for part in latest_version.release)
     else:
+        version = ".".join(str(part) for part in salt_version.release)
         release_notes_path = pathlib.Path("doc/topics/releases") / "{}.md".format(
-            ".".join(str(part) for part in salt_version.release)
+            version
         )
-    if not release_notes_path.exists():
-        release_notes_path.write_text(
+
+    template_release_path = (
+        release_notes_path.parent / "templates" / f"{version}.md.template"
+    )
+    if not template_release_path.exists():
+        template_release_path.write_text(
             textwrap.dedent(
                 f"""\
                 (release-{salt_version})=
-                # Salt {salt_version} release notes - UNRELEASED
+                # Salt {salt_version} release notes{{{{ unreleased }}}}
+                {{{{ warning }}}}
+
+                <!--
+                Add release specific details below
+                -->
+
+                <!--
+                Do not edit the changelog below.
+                This is auto generated.
+                -->
+                ## Changelog
+                {{{{ changelog }}}}
                 """
             )
         )
-        ctx.run("git", "add", str(release_notes_path))
-        ctx.info(f"Created bare {release_notes_path} release notes file")
-
-    existing = release_notes_path.read_text()
+        ctx.run("git", "add", str(template_release_path))
+        ctx.info(f"Created template {template_release_path} release notes file")
+        if template_only:
+            # Only generate the template for a new release
+            return
 
+    unreleased = " - UNRELEASED"
+    warning = f"""
+<!---
+Do not edit this file. This is auto generated.
+Edit the templates in doc/topics/releases/templates/
+for a given release.
+-->
+    """
     if release is True:
-        existing = existing.replace(" - UNRELEASED", "")
+        unreleased = ""
 
     tmp_release_notes_path = (
         release_notes_path.parent / f"{release_notes_path.name}.tmp"
     )
-    tmp_release_notes_path.write_text(f"{existing}\n## Changelog\n{changes}")
+
+    # render the release notes jinja template
+    environment = Environment(loader=FileSystemLoader(template_release_path.parent))
+    template = environment.get_template(template_release_path.name)
+    content = template.render(
+        {"changelog": changes, "unreleased": unreleased, "warning": warning}
+    )
+
+    tmp_release_notes_path.write_text(content)
     try:
         contents = tmp_release_notes_path.read_text().strip()
         if draft:
             ctx.print(contents, soft_wrap=True)
         else:
+            new_release_file = False
+            if not release_notes_path.exists():
+                new_release_file = True
             release_notes_path.write_text(contents)
+            if new_release_file:
+                ctx.run("git", "add", str(release_notes_path))
+                ctx.info(f"Created bare {release_notes_path} release notes file")
     finally:
         os.remove(tmp_release_notes_path)