feat: changelog action & example

doc-changelog/action.yml

@@ -0,0 +1,165 @@
+name: >
+  Documentation Changelog
+
+description: |
+  Adds a newsfragment to the target repository using ``towncrier``
+  containing the title and number of the pull request.
+
+  This action will only work on Linux/macOS runners.
+
+inputs:
+  # Required inputs
+
+  token:
+    description: >
+      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
+
+  # Optional inputs
+
+  python-version:
+    description: >
+      Python version used for setting up Python.
+    default: '3.10'
+    required: false
+    type: string
+
+  use-python-cache:
+    description: >
+      Whether to use the Python cache for installing previously downloaded
+      libraries. If ``true``, previously downloaded libraries are installed from the
+      Python cache. If ``false``, libraries are downloaded from the PyPI index.
+    required: false
+    default: true
+    type: boolean
+
+runs:
+  using: "composite"
+  steps:
+    - name: "Install Git and clone project"
+      env:
+        PR_BRANCH: ${{ github.event.pull_request.head.ref }}
+      uses: actions/checkout@v4
+      with:
+        # Required to checkout branch from origin rather than remote
+        ref: ${{ env.PR_BRANCH }}
+
+    - name: "Set up Python ${{ inputs.python-version }}"
+      env:
+        PYTHON_VERSION: ${{ inputs.python-version }}
+        PYTHON_CACHE: ${{ inputs.use-python-cache }}
+      uses: ansys/actions/_setup-python@main
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+        use-cache: ${{ env.PYTHON_CACHE }}
+
+    - name: "Install towncrier"
+      shell: bash
+      run: |
+        python -m pip install --upgrade pip towncrier
+
+    - name: "Get labels in the pull request"
+      env:
+        OWNER: ${{ github.repository_owner }}
+        REPO_NAME: ${{ github.event.repository.name }}
+        PR_NUMBER: ${{ github.event.number }}
+        GH_TOKEN: ${{ inputs.token }}
+      shell: bash
+      run: |
+        # Get the labels in the pull request
+        pr_labels=$(gh api repos/${{ env.OWNER }}/${{ env.REPO_NAME }}/pulls/${{ env.PR_NUMBER }} --jq '.labels.[].name')
+
+        # Save the labels to an environment variable
+        # For example, LABELS="enhancement maintenance"
+        echo LABELS='"'$pr_labels'"' >> $GITHUB_ENV
+
+    - name: "Set PR label environment variable"
+      shell: python
+      run: |
+        import os
+
+        # Create a list of labels found in the pull request
+        # For example, "enhancement maintenance".split() -> ["enhancement", "maintenance"]
+        existing_labels = ${{ env.LABELS }}.split()
+
+        # Dictionary with the key as a label from .github/workflows/label.yml and
+        # value as the corresponding section in the changelog
+        pr_labels = {
+          "enhancement": "added",
+          "bug": "fixed",
+          "dependencies": "dependencies",
+          "maintenence": "changed"
+        }
+
+        def get_changelog_section(pr_labels, existing_labels):
+          """Find the changelog section corresponding to the label in the PR."""
+          label_type = ""
+
+          for key, value in pr_labels.items():
+              if key in existing_labels:
+                  label_type = value
+                  return label_type
+
+          # If no labels are in the PR, it goes into the miscellaneous category
+          label_type = "miscellaneous"
+          return label_type
+
+        # Get the GITHUB_ENV variable
+        github_env = os.getenv('GITHUB_ENV')
+
+        # Append the PR_LABEL with its value to GITHUB_ENV
+        # For example, PR_LABEL="added" if the PR had an "enhancement" label
+        with open(github_env, "a") as f:
+            f.write(f"PR_LABEL={get_changelog_section(pr_labels, existing_labels)}")
+
+    - name: "Remove PR fragment file if it already exists"
+      env:
+        PR_NUMBER: ${{ github.event.number }}
+      shell: bash
+      run: |
+        # Find files containing the PR number
+        # For example, 20.*.md
+        file=`find . -type f -name "${{ env.PR_NUMBER }}.*.md"`
+
+        # If the fragment file exists, then delete the file
+        if [ ! -z "$file" ]; then
+          echo "Removing $file"
+          rm $file
+        fi
+
+    - name: "Create and commit towncrier fragment"
+      env:
+        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
+        # For example, 20.added.md
+        fragment="${{ env.PR_NUMBER }}.${{ env.PR_LABEL }}.md"
+
+        # Create changelog fragment with towncrier
+        # Fragment file contains the title of the PR
+        towncrier create -c "${{ env.PR_TITLE }}" $fragment
+
+        # Configure git username & email
+        git config user.name 'github-actions[bot]'
+        git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+        # Add towncrier fragment
+        git add .
+
+        # Check if file was modified
+        modified=`git diff HEAD --name-only`
+
+        # If the file was modified, commit & push it to the branch
+        if [ ! -z "$modified" ]; then
+          echo "modified: $modified"
+          # Commit and push fragment
+          git commit -m "Adding changelog entry: $fragment"
+          git push
+        fi

doc/source/doc-actions/examples/doc-changelog-basic.yml

@@ -0,0 +1,21 @@
+# Add these lines to .github/workflows/label.yml so the changelog fragment
+# is updated when the PR is labeled & the title changes:
+# on:
+#   pull_request:
+#     # opened, reopened, and synchronize are default for pull_request
+#     # edited - when PR title or body is changed
+#     # labeled - when labels are added to PR
+#     types: [opened, reopened, synchronize, edited, labeled]
+
+# Put changelog-fragment action in .github/workflows/label.yml
+changelog-fragment:
+  name: "Create changelog fragment"
+  needs: [labeler]
+  permissions:
+    contents: write
+    pull-requests: write
+  runs-on: ubuntu-latest
+  steps:
+    - uses: ansys/actions/doc-changelog@{{ version }}
+      with:
+        token: ${{ '{{ secrets.GITHUB_TOKEN }}' }}

doc/source/migration_guide.rst

@@ -7,22 +7,180 @@
 from one version of the actions to another, and other upstream dependencies that
 have been updated.
 
 Development version
 -------------------
 
 **New features:**
 
-- Obscuring vulnerabilities results in ``ansys/action/check-vulnerabilities``. This is useful when you want to hide the
+- 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/action/check-vulnerabilities``.
+- Avoid creating issues by default if vulnerabilities are found in ``ansys/actions/check-vulnerabilities``.
+- Create a changelog fragment file for each pull request using ``towncrier`` in ``ansys/actions/doc-changelog``.
 
 **Breaking Changes:**
 
 - N/A
 
 **Migration Steps:**
 
-- N/A
+- 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``.
+
+    .. code:: python
+
+        [tool.towncrier]
+        directory = "changelog.d"
+        filename = "CHANGELOG.md"
+        start_string = "<!-- towncrier release notes start -->\n"
+        underlines = ["", "", ""]
+        template = "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 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:
+
+    .. 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/changelog.d/>.
+
+        <!-- towncrier release notes start -->
+
+  .. 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:
+
+      .. code:: md
+
+          <!-- towncrier release notes start -->
+
+          ## [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.
+
+    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
+
+      on:
+        pull_request:
+          # opened, reopened, and synchronize are default for pull_request
+          # edited - when PR title or body is changed
+          # 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:
+
+    .. code:: yml
+
+        changelog-fragment:
+          name: "Create changelog fragment"
+          needs: [labeler]
+          permissions:
+            contents: write
+            pull-requests: write
+          runs-on: ubuntu-latest
+          steps:
+            - uses: ansys/actions/doc-changelog@feat/changelog-action
+              with:
+                token: ${{ secrets.GITHUB_TOKEN }}
+
+  5. Steps 1-4 are only required for setup. Here are extra commands that could be helpful:
+
+  Create a changelog file manually:
+
+  .. code:: bash
+
+      towncrier create -c "Added a feature!" 1.added.md
+
+  .. note::
+
+      "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
+
+          ## [version](https://github.com/ansys/{repo-name}/releases/tag/v{version})
+
+          ### Added
+
+          - 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
+  update CHANGELOG.md with the files in changelog.d, 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 CHANGELOG.md, but keep the changelog.d files, run the following command:
+
+  .. code:: bash
+
+      towncrier build --keep --version {version}
+
+  If you only want to preview the changelog, but don't want to make changes to CHANGELOG.md,
+  run the following command:
+
+  .. code:: bash
+
+      towncrier build --keep --draft --version {version}
+
 
 Version ``v5``
 --------------
@@ -30,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.