Skip to content

Commit

Permalink
chore: enhance doc-changelog migration guide (#499)
Browse files Browse the repository at this point in the history 
Co-authored-by: Roberto Pastor Muela <[email protected]>
  • Loading branch information
@klmcadams @RobPasMue
klmcadams and RobPasMue authored Jun 10, 2024
1 parent 85bf05b commit 854d1cd
Show file tree
Hide file tree
Showing 2 changed files with 176 additions and 116 deletions.
291 changes: 175 additions & 116 deletions doc/source/migrations/docs-changelog-setup.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/ansys/pyansys-geometry/pull/1023/files>`_
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.<product>.<library>`` with the name under ``tool.flit.module``. For example, ``ansys.geometry.core``.

.. code:: toml
[tool.towncrier]
package = "ansys.<product>.<library>"
directory = "doc/changelog.d"
filename = "CHANGELOG.md"
start_string = "<!-- towncrier release notes start -->\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 <https://github.com/ansys/{repo-name}/tree/main/doc/changelog.d/>.
<!-- towncrier release notes start -->
.. 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
<!-- towncrier release notes start -->
## [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:

Expand Down Expand Up @@ -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
Expand All @@ -149,20 +85,27 @@ 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 <https://github.com/{org-name}/{repo-name}/blob/main/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
.. toctree::
:hidden:
:maxdepth: 3
changelog
<other files>
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
Expand All @@ -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.<product>.<library> 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.<product>.<library>`` with the name under ``tool.flit.module``. For example, ``ansys.geometry.core``.

.. code:: toml
Expand All @@ -187,23 +142,132 @@ the repository has a ``docs`` directory with a Sphinx documentation setup.
title_format = "`{version} <https://github.com/{org-name}/{repo-name}/releases/tag/v{version}>`_ - {project_date}"
issue_format = "`#{issue} <https://github.com/{org-name}/{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
.. 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.

For example, the ``CHANGELOG.md`` file could look like this:

.. 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 <https://github.com/ansys/pyansys-geometry/pull/1138>`_ and `PyMechanical <https://github.com/ansys/pymechanical/pull/757/files>`_ 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 <https://github.com/{org-name}/{repo-name}/tree/main/doc/changelog.d/>.
<!-- towncrier release notes start -->
.. 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
<!-- towncrier release notes start -->
## [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.<product>.<library>`` with the name under ``tool.flit.module``. For example, ``ansys.geometry.core``.

.. code:: toml
[tool.towncrier]
package = "ansys.<product>.<library>"
directory = "doc/changelog.d"
filename = "CHANGELOG.md"
start_string = "<!-- towncrier release notes start -->\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 <https://github.com/ansys/pyansys-geometry/pull/1023/files>`_ pull request.

A reference pull request for the changes can be found in the `PyAnsys Geometry repository <https://github.com/ansys/pyansys-geometry/pull/1138>`_.
This pull request includes some other changes, but the changelog implementation is the same as described in this document.

``towncrier`` commands
----------------------
Expand Down Expand Up @@ -232,26 +296,21 @@ 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:

.. code:: bash
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:

Expand Down
1 change: 1 addition & 0 deletions doc/styles/config/vocabularies/ANSYS/accept.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ dev
GitHub
pytest
PyPI
toctree
towncrier
TXT
PyAnsys Dashboard
Expand Down

0 comments on commit 854d1cd

Please sign in to comment.