feat: changelog action & example

doc-changelog/action.yml

@@ -12,10 +12,9 @@ inputs:
 
   token:
     description: >
-      GitHub token for doing a git commit & push
-    permissions:
-      contents: write
-      pull-requests: write
+      GitHub token for doing a git commit & push.
+      The "contents: write" and "pull-requests: write" permissions
+      are required for this action.
     required: true
     type: string
 
@@ -136,6 +135,7 @@ runs:
         PR_BRANCH: ${{ github.event.pull_request.head.ref }}
         PR_TITLE: "${{ github.event.pull_request.title }}"
         PR_NUMBER: ${{ github.event.number }}
+        GH_TOKEN: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
       shell: bash
       run: |
         # Changelog fragment file in the following format

doc/source/migration_guide.rst

@@ -7,7 +7,7 @@
 from one version of the actions to another, and other upstream dependencies that
 have been updated.
 
 Development version
 -------------------
 
 **New features:**
@@ -15,18 +15,20 @@
 - Obscuring vulnerabilities results in ``ansys/actions/check-vulnerabilities``. This is useful when you want to hide the
   vulnerabilities from the logs, but still want to fail the action if vulnerabilities are found.
 - Avoid creating issues by default if vulnerabilities are found in ``ansys/actions/check-vulnerabilities``.
-- Create a changelog file for each pull request using towncrier in ``ansys/actions/doc-changelog``.
+- Create a changelog fragment file for each pull request using ``towncrier`` in ``ansys/actions/doc-changelog``.
 
 **Breaking Changes:**
 
 - N/A
 
 **Migration Steps:**
 
-- To set up your repository to use ``ansys/actions/doc-changelog``, follow these steps:
+- To set up your repository to use ``ansys/actions/doc-changelog``, see the
+  `changelog implementation in PyMechanical <https://github.com/ansys/pymechanical/pull/617>`_
+  or follow these steps:
 
   1. Add the following lines to the pyproject.toml file,
-     replacing {repo-name} with the name of the repository. For example, pymechanical.
+     replacing {repo-name} with the name of the repository. For example, ``pymechanical``.
 
     .. code:: python
 
@@ -65,7 +67,7 @@
         showcontent = true
 
   2. Create the changelog.d folder in the root of your repository, and create a file named changelog_template.jinja.
-     Add the following lines to the jinja file:
+     Add the following lines to the ``jinja`` file:
 
     .. code:: jinja
 
@@ -96,7 +98,7 @@
   .. note::
 
       If CHANGELOG.md already has sections for previous releases, make sure to put the
-      "towncrier release notes start" comment above the release sections. For example:
+      ``"towncrier release notes start"`` comment above the release sections. For example:
 
       .. code:: md
 
@@ -105,9 +107,9 @@
           ## [0.10.7](https://github.com/ansys/pymechanical/releases/tag/v0.10.7) - February 13 2024
 
 
-  4. Update .github/workflows/label.yml and .github/workflows/ci_cd.yml to use the changelog action.
+  4. Update ``.github/workflows/label.yml`` and ``.github/workflows/ci_cd.yml`` to use the changelog action.
 
-    Change the pull_request trigger at the top of each yml file above, so it lists the pull request actions that cause the workflows to run.
+    Change the ``pull_request`` trigger at the top of each ``.yml`` file above, so it lists the pull request actions that cause the workflows to run.
 
     .. code:: yml
 
@@ -118,7 +120,7 @@
           # labeled - when labels are added to PR
           types: [opened, reopened, synchronize, edited, labeled]
 
-    At the bottom of .github/workflows/label.yml, add the following lines for the changelog action:
+    At the bottom of ``.github/workflows/label.yml``, add the following lines for the changelog action:
 
     .. code:: yml
 
@@ -144,10 +146,10 @@
 
   .. note::
 
-      "Added a feature!" will be the content of the file named 1.added.md.
-      The number one in "1.added.md" is the pull request number and "added" is the section the
-      content of the file will go under. For example, CHANGELOG.md would look like this if
-      the above md file only existed in changelog.d:
+      "Added a feature!" adds the content of the file named 1.added.md.
+      The number one in "1.added.md" is the pull request number and "added" is a subsection
+      under the released version. For example, ``CHANGELOG.md`` would look like this if
+      the above ``.md`` file only existed in changelog.d:
 
       .. code:: md
 
@@ -186,7 +188,7 @@
 **New features:**
 
 - Added ``ansys/action/check-vulnerabilities`` to check for third party and first party vulnerabilities.
   This action uses ``bandit`` and ``safety`` to check for vulnerabilities in the code and dependencies, respectively.
 - Added ``ansys/actions/docker-style`` to check for Dockerfile style issues using ``hadolint``.
 - Allow ``vale`` version input in ``ansys/actions/doc-style`` action. By default, ``2.29.6`` is used.
 - Allow using the twine ``--skip-existing`` flag in the ``ansys/actions/release-pypi-*`` actions.