From 854d1cd8dbb3e17004061be7a75368c2a3cd1053 Mon Sep 17 00:00:00 2001 From: Kerry McAdams <58492561+klmcadams@users.noreply.github.com> Date: Mon, 10 Jun 2024 08:44:23 -0400 Subject: [PATCH] chore: enhance doc-changelog migration guide (#499) Co-authored-by: Roberto Pastor Muela <37798125+RobPasMue@users.noreply.github.com> --- .../migrations/docs-changelog-setup.rst | 291 +++++++++++------- .../config/vocabularies/ANSYS/accept.txt | 1 + 2 files changed, 176 insertions(+), 116 deletions(-) diff --git a/doc/source/migrations/docs-changelog-setup.rst b/doc/source/migrations/docs-changelog-setup.rst index 6311270c2..d0be79216 100644 --- a/doc/source/migrations/docs-changelog-setup.rst +++ b/doc/source/migrations/docs-changelog-setup.rst @@ -3,98 +3,15 @@ Doc-changelog action setup ========================== -To set up your repository to use the ``ansys/actions/doc-changelog`` action, see -`changelog implementation in PyAnsys-Geometry `_ -or follow these steps: +The release notes for your project can either be in your documentation or the ``CHANGELOG.md`` file. +Follow the instructions in the `update the workflow <#update-the-workflow>`_ section to add the ``ansys/actions/doc-changelog`` action +to your workflow, and then choose between adding the release notes in your documentation +or the ``CHANGELOG.md`` file. +Update the workflow +------------------- -1. Add the following lines to the ``pyproject.toml`` file, replacing ``{repo-name}`` with the name of the repository. For example, ``pyansys-geometry``. -Also, replace ``ansys..`` with the name under ``tool.flit.module``. For example, ``ansys.geometry.core``. - -.. code:: toml - - [tool.towncrier] - package = "ansys.." - directory = "doc/changelog.d" - filename = "CHANGELOG.md" - start_string = "\n" - underlines = ["", "", ""] - template = "doc/changelog.d/changelog_template.jinja" - title_format = "## [{version}](https://github.com/ansys/{repo-name}/releases/tag/v{version}) - {project_date}" - issue_format = "[#{issue}](https://github.com/ansys/{repo-name}/pull/{issue})" - - [[tool.towncrier.type]] - directory = "added" - name = "Added" - showcontent = true - - [[tool.towncrier.type]] - directory = "changed" - name = "Changed" - showcontent = true - - [[tool.towncrier.type]] - directory = "fixed" - name = "Fixed" - showcontent = true - - [[tool.towncrier.type]] - directory = "dependencies" - name = "Dependencies" - showcontent = true - - [[tool.towncrier.type]] - directory = "miscellaneous" - name = "Miscellaneous" - showcontent = true - -| - -2. Create the ``doc/changelog.d`` directory and then within it add a file named ``changelog_template.jinja`` that contains the following lines: - -.. code:: jinja - - {% if sections[""] %} - {% for category, val in definitions.items() if category in sections[""] %} - - ### {{ definitions[category]['name'] }} - - {% for text, values in sections[""][category].items() %} - - {{ text }} {{ values|join(', ') }} - {% endfor %} - - {% endfor %} - {% else %} - No significant changes. - - - {% endif %} - -| - -3. Add the following lines to the ``CHANGELOG.md`` file, replacing ``{repo-name}`` with the name of the repository: - -.. code:: md - - This project uses [towncrier](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in . - - - - -.. note:: - - If the ``CHANGELOG.md`` file already has sections for previous releases, make sure to put the - ``"towncrier release notes start"`` comment before the release sections. For example: - - .. code:: md - - - - ## [0.10.7](https://github.com/ansys/pymechanical/releases/tag/v0.10.7) - February 13 2024 - -| - -4. Update the ``.github/workflows/label.yml`` file to use the changelog action. +Update the ``.github/workflows/label.yml`` file to use the changelog action. Change the ``pull_request`` trigger at the top of the preceding ``.yml`` file so that it lists the pull request actions that cause the workflows to run: @@ -123,15 +40,34 @@ At the end of the ``.github/workflows/label.yml`` file, add the following lines with: token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }} +Next, follow the instructions to create release notes in your `documentation <#include-the-release-notes-in-your-documentation>`_ or `CHANGELOG.md file <#include-the-release-notes-in-changelog-md>`_ depending on your preference. + +Include the release notes in your documentation +----------------------------------------------- + +1. Create the ``doc/changelog.d`` directory and then within it add a file named ``changelog_template.jinja`` that contains the following lines: + +.. code:: jinja + + {% if sections[""] %} + {% for category, val in definitions.items() if category in sections[""] %} + + {{ definitions[category]['name'] }} + {% set underline = '^' * definitions[category]['name']|length %} + {{ underline }} + + {% for text, values in sections[""][category].items() %} + - {{ text }} {{ values|join(', ') }} + {% endfor %} + + {% endfor %} + {% else %} + No significant changes. -Implementing the changelog as part of your documentation --------------------------------------------------------- -The previous steps set up the changelog for your repository. To implement the changelog in your documentation, -some modifications have to be performed. Based on the PyAnsys libraries standards, this section assumes that -the repository has a ``docs`` directory with a Sphinx documentation setup. + {% endif %} -1. Create a new file named ``changelog.rst`` in the ``docs`` directory. Add the following lines to the file: +2. Create a new file named ``changelog.rst`` in the ``doc/source`` directory. Add the following lines to the file: .. code:: rst @@ -149,7 +85,16 @@ the repository has a ``docs`` directory with a Sphinx documentation setup. .. vale on -2. Add the ``changelog.rst`` file to the ``index.rst`` file in the ``docs`` directory. +.. note:: + + If your project previously used ``CHANGELOG.md`` to record the release notes, change the description under "Release notes," replacing ``{org-name}`` and ``{repo-name}`` with the name of the organization and repository respectively, and ``{latest-version}`` with the most recent version in your ``CHANGELOG.md`` file: + + .. code:: rst + + This document contains the release notes for the project. See release notes for v{latest-version} and earlier + in `CHANGELOG.md `_. + +3. Add ``changelog`` to the toctree list in the ``doc/source/index.rst`` file. ``changelog`` is placed last in the ``toctree`` list, so the "Release notes" tab is last in the documentation. .. code:: rst @@ -157,12 +102,10 @@ the repository has a ``docs`` directory with a Sphinx documentation setup. :hidden: :maxdepth: 3 - changelog + changelog - -3. Add the following lines to the ``conf.py`` file in the ``docs`` directory, replacing ``{repo-name}`` - and ``{org-name}`` with the name of the repository: +4. Add the following lines to the ``doc/source/conf.py`` file, replacing ``{org-name}`` and ``{repo-name}`` with the name of the organization and repository respectively: .. code:: python @@ -173,8 +116,20 @@ the repository has a ``docs`` directory with a Sphinx documentation setup. f"https://github.com/{org-name}/{repo-name}/releases/tag/v{__version__}" ) -4. Modify the ``pyproject.toml`` file to include the following lines, replacing ``{repo-name}`` - and ``{org-name}`` with the name of the repository: +.. note:: + + This assumes the following code already exists in the ``doc/source/conf.py`` file: + + .. code:: python + + from ansys_sphinx_theme import get_version_match + from ansys.. import __version__ + + release = version = __version__ + switcher_version = get_version_match(version) + +5. Add the following lines to the ``pyproject.toml`` file, replacing ``{org-name}`` and ``{repo-name}`` with the name of the organization and repository respectively. +Also, replace ``ansys..`` with the name under ``tool.flit.module``. For example, ``ansys.geometry.core``. .. code:: toml @@ -187,9 +142,34 @@ the repository has a ``docs`` directory with a Sphinx documentation setup. title_format = "`{version} `_ - {project_date}" issue_format = "`#{issue} `_" + [[tool.towncrier.type]] + directory = "added" + name = "Added" + showcontent = true + + [[tool.towncrier.type]] + directory = "changed" + name = "Changed" + showcontent = true + + [[tool.towncrier.type]] + directory = "fixed" + name = "Fixed" + showcontent = true + + [[tool.towncrier.type]] + directory = "dependencies" + name = "Dependencies" + showcontent = true + + [[tool.towncrier.type]] + directory = "miscellaneous" + name = "Miscellaneous" + showcontent = true + .. note:: - The previous ``CHANGELOG.md`` file can be removed from the repository, as the changelog is now part of the documentation. + If empty, the previous ``CHANGELOG.md`` file can be removed from the repository, as the changelog is now part of the documentation. However, if the ``CHANGELOG.md`` file is kept, it can be adapted to include the link to the documentation changelog. @@ -197,13 +177,97 @@ the repository has a ``docs`` directory with a Sphinx documentation setup. .. code:: md - This project uses [towncrier](https://towncrier.readthedocs.io/) and the - changes for the upcoming release can be found in - this [repository file](doc/changelog.d/changelog.rst). + This project uses [towncrier](https://towncrier.readthedocs.io/). Changes for the upcoming release can be found in + [changelog.rst](doc/source/changelog.rst). + +Reference pull requests for the changes can be found in the `PyAnsys Geometry `_ and `PyMechanical `_ repositories. +The `PyAnsys Geometry`_ pull request includes some other changes, but the changelog implementation is the same as described in this document. + +Include the release notes in ``CHANGELOG.md`` +--------------------------------------------- + +1. Create the ``doc/changelog.d`` directory and then within it add a file named ``changelog_template.jinja`` that contains the following lines: + +.. code:: jinja + + {% if sections[""] %} + {% for category, val in definitions.items() if category in sections[""] %} + + ### {{ definitions[category]['name'] }} + + {% for text, values in sections[""][category].items() %} + - {{ text }} {{ values|join(', ') }} + {% endfor %} + + {% endfor %} + {% else %} + No significant changes. + + + {% endif %} + +2. Add the following lines to the ``CHANGELOG.md`` file, replacing ``{org-name}`` and ``{repo-name}`` with the name of the organization and repository respectively: + +.. code:: md + + This project uses [towncrier](https://towncrier.readthedocs.io/) and the changes for the upcoming release can be found in . + + + + +.. note:: + + If the ``CHANGELOG.md`` file already has sections for previous releases, make sure to put the + ``"towncrier release notes start"`` comment before the release sections. For example: + + .. code:: md + + + + ## [0.10.7](https://github.com/ansys/pymechanical/releases/tag/v0.10.7) - February 13 2024 + +3. Add the following lines to the ``pyproject.toml`` file, replacing ``{org-name}`` and ``{repo-name}`` with the name of the organization and repository respectively. +Also, replace ``ansys..`` with the name under ``tool.flit.module``. For example, ``ansys.geometry.core``. + +.. code:: toml + + [tool.towncrier] + package = "ansys.." + directory = "doc/changelog.d" + filename = "CHANGELOG.md" + start_string = "\n" + underlines = ["", "", ""] + template = "doc/changelog.d/changelog_template.jinja" + title_format = "## [{version}](https://github.com/ansys/{repo-name}/releases/tag/v{version}) - {project_date}" + issue_format = "[#{issue}](https://github.com/ansys/{repo-name}/pull/{issue})" + + [[tool.towncrier.type]] + directory = "added" + name = "Added" + showcontent = true + [[tool.towncrier.type]] + directory = "changed" + name = "Changed" + showcontent = true + + [[tool.towncrier.type]] + directory = "fixed" + name = "Fixed" + showcontent = true + + [[tool.towncrier.type]] + directory = "dependencies" + name = "Dependencies" + showcontent = true + + [[tool.towncrier.type]] + directory = "miscellaneous" + name = "Miscellaneous" + showcontent = true + +A reference pull request for these changes can be found in the `PyAnsys Geometry #1023 `_ pull request. -A reference pull request for the changes can be found in the `PyAnsys Geometry repository `_. -This pull request includes some other changes, but the changelog implementation is the same as described in this document. ``towncrier`` commands ---------------------- @@ -232,9 +296,8 @@ Create a changelog file manually: - Added a feature [#1](https://github.com/ansys/{repo-name}/pull/1) -| - -When you are ready to do a release for your repository, run the following command to +When you are ready to do a release for your repository, set up the ``ansys/actions/doc-deploy-changelog`` action +to automate the process of generating the changelog. If you want to do it manually, run the following command to update the ``CHANGELOG.md`` file with the files in the ``changelog.d`` directory, replacing ``{version}`` with your release number. For example, ``0.10.8``. Do not include "v" in the version: @@ -242,16 +305,12 @@ release number. For example, ``0.10.8``. Do not include "v" in the version: towncrier build --yes --version {version} -| - If you want to update the ``CHANGELOG.md`` file but keep the files in the ``changelog.d`` directory, run this command: .. code:: bash towncrier build --keep --version {version} -| - If you only want to preview the changelog and not make changes to the ``CHANGELOG.md`` file, run the following command: diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index d9fdc57c2..9759e2d88 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -5,6 +5,7 @@ dev GitHub pytest PyPI +toctree towncrier TXT PyAnsys Dashboard