feat: doc-changelog conventional commits

doc-changelog/action.yml

@@ -65,6 +65,14 @@ inputs:
     default: true
     type: boolean
 
+  use-labels:
+    description: >
+      Whether to use labels to categorize towncrier fragments or conventional
+      commits.
+    required: false
+    default: false
+    type: boolean
+
 runs:
   using: "composite"
   steps:
@@ -91,7 +99,49 @@ runs:
       run: |
         python -m pip install --upgrade pip towncrier==${{ inputs.towncrier-version }}
 
+    - name: "Get first letter of conventional commit type"
+      if: ${{ inputs.use-labels == 'false' }}
+      env:
+        PR_TITLE: ${{ github.event.pull_request.title }}
+      shell: python
+      run: |
+        import sys
+        sys.path.insert(1, '${{ github.action_path }}/../doc-changelog/')
+
+        from parse_pr_title import get_first_letter_case
+
+        pr_title = """${{ env.PR_TITLE }}"""
+        get_first_letter_case(pr_title)
+
+    - name: "Check pull-request title follows conventional commits style"
+      if: ${{ env.FIRST_LETTER == 'lowercase' }}
+      uses: ansys/actions/commit-style@v6
+      with:
+        token: ${{ inputs.token }}
+
+    - name: "Check pull-request title follows conventional commits style with upper case"
+      if: ${{ env.FIRST_LETTER == 'uppercase' }}
+      uses: ansys/actions/commit-style@v6
+      with:
+        token: ${{ inputs.token }}
+        use-upper-case: true
+
+    - name: "Get conventional commit type from title"
+      if: ${{ inputs.use-labels == 'false' }}
+      env:
+        PR_TITLE: ${{ github.event.pull_request.title }}
+      shell: python
+      run: |
+        import sys
+        sys.path.insert(1, '${{ github.action_path }}/../doc-changelog/')
+
+        from parse_pr_title import get_conventional_commit_type
+
+        pr_title = """${{ env.PR_TITLE }}"""
+        get_conventional_commit_type(pr_title)
+
     - name: "Get labels in the pull request"
+      if: ${{ inputs.use-labels == 'true' }}
       env:
         OWNER: ${{ github.repository_owner }}
         REPO_NAME: ${{ github.event.repository.name }}
@@ -106,44 +156,29 @@ runs:
         # For example, LABELS="enhancement maintenance"
         echo LABELS='"'$pr_labels'"' >> $GITHUB_ENV
 
+    - name: "Set CHANGELOG category based on conventional commit type"
+      if: ${{ inputs.use-labels == 'false' }}
+      shell: python
+      run: |
+        import sys
+        sys.path.insert(1, '${{ github.action_path }}/../doc-changelog/')
+
+        from parse_pr_title import changelog_category_cc
+
+        cc_type = ${{ env.CC_TYPE }}
+        changelog_category_cc(cc_type)
+
     - name: "Set PR label environment variable"
+      if: ${{ inputs.use-labels == 'true' }}
       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",
-          "maintenance": "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)}")
+        import sys
+        sys.path.insert(1, '${{ github.action_path }}/../doc-changelog/')
+
+        from parse_pr_title import changelog_cateogry_labels
+
+        labels = ${{ env.LABELS }}
+        changelog_cateogry_labels(labels)
 
     - name: "Remove PR fragment file if it already exists"
       env:
@@ -165,23 +200,19 @@ runs:
         PR_TITLE: ${{ github.event.pull_request.title }}
       shell: python
       run: |
-        import os
-
-        # Retrieve title
-        clean_title = os.getenv('PR_TITLE')
-
-        # Remove extra whitespace
-        clean_title = clean_title.strip()
+        import sys
+        sys.path.insert(1, '${{ github.action_path }}/../doc-changelog/')
 
-        # Add backslash in front of backtick and double quote
-        clean_title = clean_title.replace("`", "\`").replace('"', '\\"')
+        from parse_pr_title import clean_pr_title
 
-        # Get the GITHUB_ENV variable
-        github_env = os.getenv('GITHUB_ENV')
+        pr_title = """${{ env.PR_TITLE }}"""
+        use_labels = "${{ inputs.use-labels }}"
+        use_labels = use_labels[0].upper() + use_labels[1:]
 
-        # Append the CLEAN_TITLE with its value to GITHUB_ENV
-        with open(github_env, "a") as f:
-            f.write(f"CLEAN_TITLE={clean_title}")
+        if use_labels == "True":
+          clean_pr_title(pr_title, use_labels)
+        else:
+          clean_pr_title(pr_title, use_labels)
 
     - name: "Create and commit towncrier fragment"
       env:
@@ -191,7 +222,7 @@ runs:
       run: |
         # Changelog fragment file in the following format
         # For example, 20.added.md
-        fragment="${{ env.PR_NUMBER }}.${{ env.PR_LABEL }}.md"
+        fragment="${{ env.PR_NUMBER }}.${{ env.CHANGELOG_SECTION }}.md"
 
         # Create changelog fragment with towncrier
         # Fragment file contains the title of the PR

doc-changelog/parse_pr_title.py

@@ -0,0 +1,118 @@
+import os
+
+
+def save_env_variable(env_var_name, env_var_value):
+    # Get the GITHUB_ENV variable
+    github_env = os.getenv("GITHUB_ENV")
+
+    # Save environment variable with its value
+    with open(github_env, "a") as f:
+        f.write(f"{env_var_name}={env_var_value}")
+
+
+def get_first_letter_case(pr_title):
+    pr_title = f"""{pr_title}"""
+    index = 0
+    first_letter = pr_title[index]
+
+    print(pr_title)
+
+    while first_letter == " ":
+        index += 1
+        try:
+            first_letter = pr_title[index]
+        except IndexError:
+            print("Pull request title is blank")
+            exit(1)
+
+    if first_letter.islower():
+        save_env_variable("FIRST_LETTER", "lowercase")
+    else:
+        save_env_variable("FIRST_LETTER", "uppercase")
+
+
+def get_conventional_commit_type(pr_title):
+    pr_title = f"""{pr_title}"""
+    colon_index = pr_title.index(":")
+    cc_type = '"' + pr_title[:colon_index] + '"'
+    save_env_variable("CC_TYPE", cc_type)
+
+
+def changelog_category_cc(cc_type):
+    # Get conventional commit type from env variable
+    cc_type = cc_type.lower()
+
+    print(cc_type)
+
+    cc_type_changelog_dict = {
+        "feat": "added",
+        "fix": "fixed",
+        "docs": "documentation",
+        "build": "dependencies",
+        "revert": "miscellaneous",
+        "style": "miscellaneous",
+        "refactor": "miscellaneous",
+        "perf": "miscellaneous",
+        "test": "test",
+        "chore": "maintenance",
+        "ci": "maintenance",
+    }
+
+    changelog_section = cc_type_changelog_dict[cc_type]
+
+    save_env_variable("CHANGELOG_SECTION", changelog_section)
+
+
+def changelog_cateogry_labels(labels):
+    # Create a list of labels found in the pull request
+    # For example, "enhancement maintenance".split() -> ["enhancement", "maintenance"]
+    existing_labels = 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",
+        "documentation": "documentation",
+        "testing": "test",
+        "dependencies": "dependencies",
+        "CI/CD": "maintenance",
+        "maintenance": "maintenance",
+    }
+
+    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
+
+    save_env_variable(
+        "CHANGELOG_SECTION", get_changelog_section(pr_labels, existing_labels)
+    )
+
+
+def clean_pr_title(pr_title, use_labels):
+    # Retrieve title
+    clean_title = pr_title
+
+    # If not using label, remove conventional commit type from title
+    if use_labels == "False":
+        colon_index = clean_title.index(":")
+        clean_title = clean_title[colon_index + 1 :]
+
+    print(clean_title)
+
+    # Remove extra whitespace
+    clean_title = clean_title.strip()
+
+    # Add backslash in front of backtick and double quote
+    clean_title = clean_title.replace("`", "\\`").replace('"', '\\"')
+
+    save_env_variable("CLEAN_TITLE", clean_title)

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

@@ -20,3 +20,4 @@ changelog-fragment:
     - uses: ansys/actions/doc-changelog@{{ version }}
       with:
         token: ${{ '{{ secrets.PYANSYS_CI_BOT_TOKEN }}' }}
+        # use-labels: true  # uncomment this line to use labels instead of conventional commits

doc/source/migrations/docs-changelog-setup.rst

@@ -247,8 +247,13 @@ Also, replace ``ansys.<product>.<library>`` with the name under ``tool.flit.modu
     showcontent = true
 
     [[tool.towncrier.type]]
-    directory = "changed"
-    name = "Changed"
+    directory = "dependencies"
+    name = "Dependencies"
+    showcontent = true
+
+    [[tool.towncrier.type]]
+    directory = "documentation"
+    name = "Documentation"
     showcontent = true
 
     [[tool.towncrier.type]]
@@ -257,15 +262,20 @@ Also, replace ``ansys.<product>.<library>`` with the name under ``tool.flit.modu
     showcontent = true
 
     [[tool.towncrier.type]]
-    directory = "dependencies"
-    name = "Dependencies"
+    directory = "maintenance"
+    name = "Maintenance"
     showcontent = true
 
     [[tool.towncrier.type]]
     directory = "miscellaneous"
     name = "Miscellaneous"
     showcontent = true
 
+    [[tool.towncrier.type]]
+    directory = "test"
+    name = "Test"
+    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.