Repository: twisted/twisted

Issue:
Remove the requirement for a fixed merge message
> The commit format is no longer that important.
> 
> If the PR description contains `Fixes #1234` I think that the associated PR is automatically closed. This is why I am observing from here.
> 
> What we can do, is update the format of the PR title, to include the ticket id as `#1234` and not just `1234`. In this way, the commit message is auto-filled with the PR title and will have the reference to the ticket.
> 
> we can also configure GitHub to automatically delete the branch after a merge.

Yeah, I agree with all this. I think we should auto-delete branches and switch to the Github-friendly "fixes" line, and possibly dispense with the manual commit format entirely.

_Originally posted by @glyph in https://github.com/twisted/twisted/issues/11584#issuecomment-1188481007_


Discussion:

Resolving patch:
diff --git a/.github/scripts/check-pr-text.py b/.github/scripts/check-pr-text.py
new file mode 100644
--- /dev/null
+++ b/.github/scripts/check-pr-text.py
@@ -0,0 +1,62 @@
+#
+# This script is designed to be called by the GHA workflow.
+#
+# It is designed to check that the PR text complies to our dev standards.
+#
+# The input is received via the environmet variables:
+# * PR_TITLE - title of the PR
+# * PR_BODY - the description of the PR
+#
+# To test it run
+#
+# $ export PR_TITLE='#1234 Test Title'
+# $ export PR_BODY='some lines
+# > Fixes #12345
+# > more lines'
+# $ python3 .github/scripts/check-pr-text.py
+#
+import os
+import re
+import sys
+
+pr_title = os.environ.get("PR_TITLE", "")
+pr_body = os.environ.get("PR_BODY", "")
+
+print("--- DEBUG ---")
+print(f"Title: {pr_title}")
+print(f"Body:\n {pr_body}")
+print("-------------")
+
+
+def fail(message):
+    print(message)
+    print("Fix the title and then trigger a new push.")
+    print("A re-run for this job will not work.")
+    sys.exit(1)
+
+
+if not pr_title:
+    fail("Title for the PR not found. " "Maybe missing PR_TITLE env var.")
+
+if not pr_body:
+    fail("Body for the PR not found. " "Maybe missing PR_BODY env var.")
+
+title_search = re.search(r"^(#\d+) .+", pr_title)
+if not title_search:
+    fail("Title of PR has no issue ID reference.")
+else:
+    print(f"PR title is complaint for {title_search[1]}. Good job.")
+
+
+body_search = re.search(r".*Fixes (#\d+).+", pr_body)
+if not body_search:
+    fail('Body of PR has no "Fixes #12345" issue ID reference.')
+else:
+    print(f"PR description is complaint for {body_search[1]}. Good job.")
+
+
+if title_search[1] != body_search[1]:
+    fail("PR title and description have different IDs.")
+
+# All good.
+sys.exit(0)


Test patch:
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
--- a/.github/workflows/test.yaml
+++ b/.github/workflows/test.yaml
@@ -156,6 +156,29 @@ jobs:
         name: lnx-${{ matrix.python-version }}-${{ matrix.tox-env }}${{ matrix.noipv6 }}
         fail_ci_if_error: true
 
+  docs:
+    runs-on: ubuntu-20.04
+    env:
+      TOX_PARALLEL_NO_SPINNER: 1
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.9'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip tox
+
+    - name: Run the checks
+      run: |
+        python --version
+        tox --parallel -e narrativedocs
+
+
   static-checks:
     runs-on: ubuntu-20.04
     env:
@@ -179,7 +202,7 @@ jobs:
     - name: Run the checks
       run: |
         python --version
-        tox --parallel -e lint,apidocs,narrativedocs,mypy
+        tox --parallel -e lint,mypy
 
     - name: Revert merge commit for a release branch
       if: github.event_name == 'pull_request' && startsWith(github.head_ref, 'release-')
@@ -194,6 +217,16 @@ jobs:
       run: |
         tox -q -e newsfragment
 
+    # This is called only on code changes.
+    # If you forgot to define the right PR title you should re-run the job.
+    - name: Check PR title format
+      if: github.event_name == 'pull_request'
+      env:
+        PR_TITLE: ${{ github.event.pull_request.title }}
+        PR_BODY: ${{ github.event.pull_request.body }}
+      run: python .github/scripts/check-pr-text.py
+
+
 
   # Used for various release automation.
   # This is also executed for each PR to exercise the release as much
@@ -270,6 +303,7 @@ jobs:
     # Here should be the list of all the other jobs defined in this file.
     needs:
       - testing
+      - docs
       - static-checks
       - release-publish
     steps: