From a749ec551afead5ad9a17a640b1d2d2f68fd1fc2 Mon Sep 17 00:00:00 2001 From: Pedro Algarvio Date: Mon, 13 Feb 2023 18:22:31 +0000 Subject: [PATCH] Start writing the release notes in markdown. Signed-off-by: Pedro Algarvio --- doc/conf.py | 4 +- doc/topics/releases/3006.0.md | 57 ++++++++++++++++++++++ doc/topics/releases/3006.0.rst | 67 -------------------------- requirements/static/ci/docs.in | 1 + requirements/static/ci/py3.10/docs.txt | 20 ++++++++ requirements/static/ci/py3.6/docs.txt | 24 +++++++++ requirements/static/ci/py3.7/docs.txt | 21 ++++++++ requirements/static/ci/py3.8/docs.txt | 20 ++++++++ requirements/static/ci/py3.9/docs.txt | 20 ++++++++ tools/changelog.py | 7 +-- 10 files changed, 170 insertions(+), 71 deletions(-) create mode 100644 doc/topics/releases/3006.0.md delete mode 100644 doc/topics/releases/3006.0.rst diff --git a/doc/conf.py b/doc/conf.py index 024916b8084..01709bff618 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -151,7 +151,8 @@ extensions = [ "sphinx.ext.intersphinx", "httpdomain", "youtube", - "saltrepo" + "saltrepo", + "myst_parser", #'saltautodoc', # Must be AFTER autodoc #'shorturls', ] @@ -215,6 +216,7 @@ extlinks = { "formula_url": ("https://github.com/saltstack-formulas/%s", "url %s"), } +myst_gfm_only = True # ----- Localization --------------------------------------------------------> locale_dirs = ["locale/"] diff --git a/doc/topics/releases/3006.0.md b/doc/topics/releases/3006.0.md new file mode 100644 index 00000000000..a7f1967c888 --- /dev/null +++ b/doc/topics/releases/3006.0.md @@ -0,0 +1,57 @@ +[](#release-3006.0) + +# Salt 3006.0 release notes - Codename Sulfur - UNRELEASED + +## 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 `` + * 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 +``` diff --git a/doc/topics/releases/3006.0.rst b/doc/topics/releases/3006.0.rst deleted file mode 100644 index 5cd3fb7fc14..00000000000 --- a/doc/topics/releases/3006.0.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. _release-3006.0: - -=========================================== -Salt 3006.0 release notes - Codename Sulfur -=========================================== - -Salt 3006.0 is currently under development. - - -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 `_ -in the `Salt Install Guide `_ -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 `_ -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 :ref:`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 `` - * 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: - -.. code-block:: yaml - - lib-foo: - pip.installed: - - pip_bin: /usr/bin/pip3 - lib-bar: - pip.installed: - - bin_env: /usr/bin/python3 diff --git a/requirements/static/ci/docs.in b/requirements/static/ci/docs.in index ef3b49e1367..a1ec03c9c2d 100644 --- a/requirements/static/ci/docs.in +++ b/requirements/static/ci/docs.in @@ -2,3 +2,4 @@ sphinx>=3.5.1; python_version < '3.9' sphinx>=6.1.0; python_version >= '3.9' +myst-docutils[linkify] diff --git a/requirements/static/ci/py3.10/docs.txt b/requirements/static/ci/py3.10/docs.txt index e09938d2144..037a8f16a8c 100644 --- a/requirements/static/ci/py3.10/docs.txt +++ b/requirements/static/ci/py3.10/docs.txt @@ -40,24 +40,37 @@ jinja2==3.1.2 # via # -c requirements/static/ci/py3.10/linux.txt # -r requirements/base.txt + # myst-docutils # sphinx jmespath==1.0.1 # via # -c requirements/static/ci/py3.10/linux.txt # -r requirements/base.txt +linkify-it-py==1.0.3 + # via myst-docutils looseversion==1.0.2 # via # -c requirements/static/ci/py3.10/linux.txt # -r requirements/base.txt +markdown-it-py==2.1.0 + # via + # mdit-py-plugins + # myst-docutils markupsafe==2.0.1 # via # -c requirements/static/ci/py3.10/linux.txt # -r requirements/base.txt # jinja2 +mdit-py-plugins==0.3.3 + # via myst-docutils +mdurl==0.1.2 + # via markdown-it-py msgpack==1.0.2 # via # -c requirements/static/ci/py3.10/linux.txt # -r requirements/base.txt +myst-docutils[linkify]==0.18.1 + # via -r requirements/static/ci/docs.in packaging==22.0 # via # -c requirements/static/ci/py3.10/linux.txt @@ -81,6 +94,7 @@ pyyaml==5.4.1 # via # -c requirements/static/ci/py3.10/linux.txt # -r requirements/base.txt + # myst-docutils pyzmq==23.2.0 # via # -c requirements/static/ci/py3.10/linux.txt @@ -106,6 +120,12 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.5 # via sphinx +typing-extensions==4.2.0 + # via + # -c requirements/static/ci/py3.10/linux.txt + # myst-docutils +uc-micro-py==1.0.1 + # via linkify-it-py urllib3==1.26.6 # via # -c requirements/static/ci/py3.10/linux.txt diff --git a/requirements/static/ci/py3.6/docs.txt b/requirements/static/ci/py3.6/docs.txt index 14e1388003f..93859224f59 100644 --- a/requirements/static/ci/py3.6/docs.txt +++ b/requirements/static/ci/py3.6/docs.txt @@ -6,6 +6,10 @@ # alabaster==0.7.12 # via sphinx +attrs==20.3.0 + # via + # -c requirements/static/ci/py3.6/linux.txt + # markdown-it-py babel==2.9.1 # via sphinx certifi==2022.12.7 @@ -40,24 +44,37 @@ jinja2==3.0.3 # via # -c requirements/static/ci/py3.6/linux.txt # -r requirements/base.txt + # myst-docutils # sphinx jmespath==0.10.0 # via # -c requirements/static/ci/py3.6/linux.txt # -r requirements/base.txt +linkify-it-py==1.0.3 + # via myst-docutils looseversion==1.0.3 # via # -c requirements/static/ci/py3.6/linux.txt # -r requirements/base.txt +markdown-it-py==2.0.1 + # via + # mdit-py-plugins + # myst-docutils markupsafe==2.0.1 # via # -c requirements/static/ci/py3.6/linux.txt # -r requirements/base.txt # jinja2 +mdit-py-plugins==0.3.0 + # via myst-docutils +mdurl==0.1.0 + # via markdown-it-py msgpack==1.0.2 # via # -c requirements/static/ci/py3.6/linux.txt # -r requirements/base.txt +myst-docutils[linkify]==0.16.1 + # via -r requirements/static/ci/docs.in packaging==21.3 # via # -c requirements/static/ci/py3.6/linux.txt @@ -85,6 +102,7 @@ pyyaml==5.4.1 # via # -c requirements/static/ci/py3.6/linux.txt # -r requirements/base.txt + # myst-docutils pyzmq==23.2.0 # via # -c requirements/static/ci/py3.6/linux.txt @@ -110,6 +128,12 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.4 # via sphinx +typing-extensions==3.10.0.0 + # via + # -c requirements/static/ci/py3.6/linux.txt + # markdown-it-py +uc-micro-py==1.0.1 + # via linkify-it-py urllib3==1.26.6 # via # -c requirements/static/ci/py3.6/linux.txt diff --git a/requirements/static/ci/py3.7/docs.txt b/requirements/static/ci/py3.7/docs.txt index 01bc4a82c76..753a000fb87 100644 --- a/requirements/static/ci/py3.7/docs.txt +++ b/requirements/static/ci/py3.7/docs.txt @@ -40,24 +40,37 @@ jinja2==3.1.2 # via # -c requirements/static/ci/py3.7/linux.txt # -r requirements/base.txt + # myst-docutils # sphinx jmespath==1.0.1 # via # -c requirements/static/ci/py3.7/linux.txt # -r requirements/base.txt +linkify-it-py==1.0.3 + # via myst-docutils looseversion==1.0.2 # via # -c requirements/static/ci/py3.7/linux.txt # -r requirements/base.txt +markdown-it-py==2.1.0 + # via + # mdit-py-plugins + # myst-docutils markupsafe==2.0.1 # via # -c requirements/static/ci/py3.7/linux.txt # -r requirements/base.txt # jinja2 +mdit-py-plugins==0.3.3 + # via myst-docutils +mdurl==0.1.2 + # via markdown-it-py msgpack==1.0.2 # via # -c requirements/static/ci/py3.7/linux.txt # -r requirements/base.txt +myst-docutils[linkify]==0.18.1 + # via -r requirements/static/ci/docs.in packaging==21.3 # via # -c requirements/static/ci/py3.7/linux.txt @@ -85,6 +98,7 @@ pyyaml==5.4.1 # via # -c requirements/static/ci/py3.7/linux.txt # -r requirements/base.txt + # myst-docutils pyzmq==23.2.0 # via # -c requirements/static/ci/py3.7/linux.txt @@ -110,6 +124,13 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.4 # via sphinx +typing-extensions==3.10.0.0 + # via + # -c requirements/static/ci/py3.7/linux.txt + # markdown-it-py + # myst-docutils +uc-micro-py==1.0.1 + # via linkify-it-py urllib3==1.26.6 # via # -c requirements/static/ci/py3.7/linux.txt diff --git a/requirements/static/ci/py3.8/docs.txt b/requirements/static/ci/py3.8/docs.txt index 9c23c81a80d..a6b9f1184ef 100644 --- a/requirements/static/ci/py3.8/docs.txt +++ b/requirements/static/ci/py3.8/docs.txt @@ -40,24 +40,37 @@ jinja2==3.1.2 # via # -c requirements/static/ci/py3.8/linux.txt # -r requirements/base.txt + # myst-docutils # sphinx jmespath==1.0.1 # via # -c requirements/static/ci/py3.8/linux.txt # -r requirements/base.txt +linkify-it-py==1.0.3 + # via myst-docutils looseversion==1.0.2 # via # -c requirements/static/ci/py3.8/linux.txt # -r requirements/base.txt +markdown-it-py==2.1.0 + # via + # mdit-py-plugins + # myst-docutils markupsafe==2.0.1 # via # -c requirements/static/ci/py3.8/linux.txt # -r requirements/base.txt # jinja2 +mdit-py-plugins==0.3.3 + # via myst-docutils +mdurl==0.1.2 + # via markdown-it-py msgpack==1.0.2 # via # -c requirements/static/ci/py3.8/linux.txt # -r requirements/base.txt +myst-docutils[linkify]==0.18.1 + # via -r requirements/static/ci/docs.in packaging==22.0 # via # -c requirements/static/ci/py3.8/linux.txt @@ -81,6 +94,7 @@ pyyaml==5.4.1 # via # -c requirements/static/ci/py3.8/linux.txt # -r requirements/base.txt + # myst-docutils pyzmq==23.2.0 # via # -c requirements/static/ci/py3.8/linux.txt @@ -106,6 +120,12 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.4 # via sphinx +typing-extensions==4.2.0 + # via + # -c requirements/static/ci/py3.8/linux.txt + # myst-docutils +uc-micro-py==1.0.1 + # via linkify-it-py urllib3==1.26.6 # via # -c requirements/static/ci/py3.8/linux.txt diff --git a/requirements/static/ci/py3.9/docs.txt b/requirements/static/ci/py3.9/docs.txt index caf55df5df8..324c30545c9 100644 --- a/requirements/static/ci/py3.9/docs.txt +++ b/requirements/static/ci/py3.9/docs.txt @@ -44,24 +44,37 @@ jinja2==3.1.2 # via # -c requirements/static/ci/py3.9/linux.txt # -r requirements/base.txt + # myst-docutils # sphinx jmespath==1.0.1 # via # -c requirements/static/ci/py3.9/linux.txt # -r requirements/base.txt +linkify-it-py==1.0.3 + # via myst-docutils looseversion==1.0.2 # via # -c requirements/static/ci/py3.9/linux.txt # -r requirements/base.txt +markdown-it-py==2.1.0 + # via + # mdit-py-plugins + # myst-docutils markupsafe==2.0.1 # via # -c requirements/static/ci/py3.9/linux.txt # -r requirements/base.txt # jinja2 +mdit-py-plugins==0.3.3 + # via myst-docutils +mdurl==0.1.2 + # via markdown-it-py msgpack==1.0.2 # via # -c requirements/static/ci/py3.9/linux.txt # -r requirements/base.txt +myst-docutils[linkify]==0.18.1 + # via -r requirements/static/ci/docs.in packaging==22.0 # via # -c requirements/static/ci/py3.9/linux.txt @@ -85,6 +98,7 @@ pyyaml==5.4.1 # via # -c requirements/static/ci/py3.9/linux.txt # -r requirements/base.txt + # myst-docutils pyzmq==23.2.0 # via # -c requirements/static/ci/py3.9/linux.txt @@ -110,6 +124,12 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.5 # via sphinx +typing-extensions==4.2.0 + # via + # -c requirements/static/ci/py3.9/linux.txt + # myst-docutils +uc-micro-py==1.0.1 + # via linkify-it-py urllib3==1.26.6 # via # -c requirements/static/ci/py3.9/linux.txt diff --git a/tools/changelog.py b/tools/changelog.py index fefd9ec8480..109cf4195c1 100644 --- a/tools/changelog.py +++ b/tools/changelog.py @@ -348,14 +348,15 @@ def update_release_notes(ctx: Context, salt_version: str, draft: bool = False): major_version = salt_version changes = _get_changelog_contents(ctx, salt_version) changes = "\n".join(changes.split("\n")[2:]) - tmpnotes = f"doc/topics/releases/{salt_version}.rst.tmp" + tmpnotes = f"doc/topics/releases/{salt_version}.md.tmp" try: - with open(f"doc/topics/releases/{major_version}.rst") as rfp: + with open(f"doc/topics/releases/{major_version}.md") as rfp: existing = rfp.read() except FileNotFoundError: existing = "" with open(tmpnotes, "w") as wfp: wfp.write(existing) + wfp.write("\n## Changelog\n") wfp.write(changes) try: with open(tmpnotes) as rfp: @@ -363,7 +364,7 @@ def update_release_notes(ctx: Context, salt_version: str, draft: bool = False): if draft: ctx.print(contents, soft_wrap=True) else: - with open(f"doc/topics/releases/{salt_version}.rst", "w") as wfp: + with open(f"doc/topics/releases/{salt_version}.md", "w") as wfp: wfp.write(contents) finally: os.remove(tmpnotes)