Various CI and doc refactors

.github/ISSUE_TEMPLATE/bug_report.md

@@ -17,8 +17,8 @@ current development version. To confirm this, you have three options:
    - create a new virtualenv (make sure it's the same Python version);
    - clone this repository;
    - run `pip install -e .[d]`;
-   - run `pip install -r test_requirements.txt`
-   - make sure it's sane by running `python -m pytest`; and
+   - run `pip install --group tests`
+   - make sure it's sane by running `python -m pytest -n auto`; and
    - run `black` like you did last time.
 -->
 

.github/ISSUE_TEMPLATE/config.yml

@@ -6,7 +6,6 @@ blank_issues_enabled: true
 contact_links:
   - name: Chat on Python Discord
     url: https://discord.gg/RtVdv86PrH
-    about: |
-      User support, questions, and other lightweight requests can be
-      handled via the #black-formatter text channel we have on Python
-      Discord.
+    about: >-
+      User support, questions, and other lightweight requests can be handled via the
+      #black-formatter text channel we have on Python Discord.

.github/ISSUE_TEMPLATE/style_issue.md

@@ -18,7 +18,7 @@ how the current _Black_ style is not great: -->
 
 ```python
 def f():
-    "Make sure this code is blackened"""
+    """This code should be formatted as per the current Black style"""
     pass
 ```
 
@@ -29,6 +29,7 @@ def f():
 ```python
 def f(
     ):
+    """This code can be formatted however you suggest!"""
     pass
 ```
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -23,8 +23,7 @@
      - Documentation changes are necessary for most formatting changes and
        other enhancements. -->
 
-- [ ] Implement any code style changes under the `--preview` style, following the
-      stability policy?
+- [ ] Implement any code style changes under the `--preview` style, following the stability policy?
 - [ ] Add an entry in `CHANGES.md` if necessary?
 - [ ] Add / update tests if necessary?
 - [ ] Add new / update outdated documentation?

.github/dependabot.yml

@@ -12,9 +12,9 @@ updates:
       default-days: 7
 
   - package-ecosystem: "pip"
-    directory: "docs/"
+    directory: "/"
     schedule:
       interval: "weekly"
-    labels: ["skip news", "C: dependencies", "T: documentation"]
+    labels: ["skip news", "C: dependencies"]
     cooldown:
       default-days: 7

.github/workflows/changelog.yml

@@ -8,9 +8,7 @@ permissions:
   contents: read
 
 jobs:
-  build:
-    name: Changelog Entry Check
-
+  check:
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/diff_shades.yml

@@ -3,10 +3,20 @@ name: diff-shades
 on:
   push:
     branches: [main]
-    paths: ["src/**", "pyproject.toml", ".github/workflows/*"]
+    paths:
+      - src/**
+      - pyproject.toml
+      - scripts/diff_shades_gha_helper.py
+      - .github/workflows/diff_shades.yml
+      - .github/workflows/diff_shades_comment.yml
 
   pull_request:
-    paths: ["src/**", "pyproject.toml", ".github/workflows/*"]
+    paths:
+      - src/**
+      - pyproject.toml
+      - scripts/diff_shades_gha_helper.py
+      - .github/workflows/diff_shades.yml
+      - .github/workflows/diff_shades_comment.yml
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
@@ -34,17 +44,14 @@ jobs:
       - uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
         with:
           python-version: "3.13"
-
-      - name: Install diff-shades and support dependencies
-        run: |
-          python -m pip install 'click>=8.1.7' packaging urllib3
-          python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
+          pip-version: "25.3"
+          pip-install: --group diff-shades --group diff-shades-comment
 
       - name: Calculate run configuration & metadata
         id: set-config
         env:
           GITHUB_TOKEN: ${{ github.token }}
-        run: python scripts/diff_shades_gha_helper.py config ${{ github.event_name }}
+        run: python scripts/diff_shades_gha_helper.py config
 
   analysis-base:
     name: analysis / base / ${{ matrix.mode }}
@@ -66,10 +73,11 @@ jobs:
       - uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
         with:
           python-version: "3.13"
+          pip-version: "25.3"
+          pip-install: --group diff-shades
 
-      - name: Install diff-shades
+      - name: Configure git
         run: |
-          python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
           git config user.name "diff-shades-gha"
           git config user.email "diff-shades-gha@example.com"
 
@@ -84,15 +92,15 @@ jobs:
         if: steps.baseline-cache.outputs.cache-hit != 'true'
         env:
           GITHUB_TOKEN: ${{ github.token }}
-        run: >
+        run: |
           ${{ matrix.baseline-setup-cmd }}
-          && python -m pip install .
+          python -m pip install .
 
       - name: Analyze baseline revision
         if: steps.baseline-cache.outputs.cache-hit != 'true'
-        run: >
-          diff-shades analyze ${{ matrix.baseline-analysis }}
-          -v --work-dir projects-cache/ ${{ matrix.force-flag }}
+        run:
+          diff-shades analyze ${{ matrix.baseline-analysis }} --work-dir projects-cache/
+          --force-${{ matrix.style }}-style -v
 
       - name: Upload baseline analysis
         uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
@@ -120,19 +128,20 @@ jobs:
       - uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
         with:
           python-version: "3.13"
+          pip-version: "25.3"
+          pip-install: --group diff-shades
 
-      - name: Install diff-shades
+      - name: Configure git
         run: |
-          python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
           git config user.name "diff-shades-gha"
           git config user.email "diff-shades-gha@example.com"
 
       - name: Build and install target revision
         env:
           GITHUB_TOKEN: ${{ github.token }}
-        run: >
+        run: |
           ${{ matrix.target-setup-cmd }}
-          && python -m pip install .
+          python -m pip install .
 
       # Pull it from previous runs - we're NOT trying to get it from this run
       # (but it wouldn't cause problems if we theoretically did)
@@ -145,16 +154,16 @@ jobs:
 
       - name: Analyze target revision (with repeated projects)
         if: steps.baseline-cache.outputs.cache-hit == 'true'
-        run: >
-          diff-shades analyze ${{ matrix.target-analysis }}
-          -v --work-dir projects-cache/ ${{ matrix.force-flag }}
+        run: |
+          diff-shades analyze ${{ matrix.target-analysis }} --work-dir projects-cache/ \
+          --force-${{ matrix.style }}-style -v \
           --repeat-projects-from ${{ matrix.baseline-analysis }}
 
       - name: Analyze target revision (without repeated projects)
         if: steps.baseline-cache.outputs.cache-hit != 'true'
-        run: >
-          diff-shades analyze ${{ matrix.target-analysis }}
-          -v --work-dir projects-cache/ ${{ matrix.force-flag }}
+        run:
+          diff-shades analyze ${{ matrix.target-analysis }} --work-dir projects-cache/
+          --force-${{ matrix.style }}-style -v
 
       - name: Upload target analysis
         uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
@@ -163,8 +172,7 @@ jobs:
           path: ${{ matrix.target-analysis }}
 
       - name: Check for failed files for target revision
-        run: >
-          diff-shades show-failed --check --show-log ${{ matrix.target-analysis }}
+        run: diff-shades show-failed --check --show-log ${{ matrix.target-analysis }}
 
   compare:
     name: compare / ${{ matrix.mode }}
@@ -188,41 +196,41 @@ jobs:
       - uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
         with:
           python-version: "3.13"
-
-      - name: Install diff-shades and support dependencies
-        run: |
-          python -m pip install 'click>=8.1.7' packaging urllib3
-          python -m pip install https://github.com/ichard26/diff-shades/archive/stable.zip
+          pip-version: "25.3"
+          pip-install: --group diff-shades --group diff-shades-comment
 
       - name: Generate HTML diff report
-        run: >
-          diff-shades --dump-html diff.html compare --diff
-          ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }}
+        run: |
+          diff-shades --dump-html diff.html \
+          compare --diff ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }}
 
       - name: Upload diff report
         uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
-          name: ${{ matrix.mode }}-diff.html
+          name: ${{ matrix.style }}-diff.html
           path: diff.html
 
       - name: Generate summary file (PR only)
-        if: github.event_name == 'pull_request' && matrix.mode == 'preview-new-changes'
-        run: >
-          python scripts/diff_shades_gha_helper.py comment-body
-          ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }}
-          ${{ matrix.baseline-sha }} ${{ matrix.target-sha }}
-          ${{ github.event.pull_request.number }}
+        if: github.event_name == 'pull_request'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          python scripts/diff_shades_gha_helper.py comment-body \
+          ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }} \
+          ${{ matrix.style }} ${{ matrix.mode }}
 
       - name: Upload summary file (PR only)
-        if: github.event_name == 'pull_request' && matrix.mode == 'preview-new-changes'
+        if: github.event_name == 'pull_request'
         uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
-          name: .pr-comment.json
-          path: .pr-comment.json
+          name: .${{ matrix.style }}.pr-comment.md
+          path: .${{ matrix.style }}.pr-comment.md
           include-hidden-files: true
 
       - name: Verify zero changes (PR only)
         if: matrix.mode == 'assert-no-changes'
-        run: >
-          diff-shades compare --check ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }}
-          || (echo "Please verify you didn't change the stable code style unintentionally!" && exit 1)
+        run: |
+          diff-shades compare --check \
+          ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }} || \
+          (echo "Please verify you didn't change the stable code style unintentionally!" \
+          && exit 1)

.github/workflows/diff_shades_comment.yml

@@ -1,4 +1,4 @@
-name: diff-shades-comment
+name: diff-shades comment
 
 on:
   workflow_run:
@@ -10,43 +10,63 @@ permissions: {}
 jobs:
   comment:
     runs-on: ubuntu-latest
+    # We want to comment even if there were failed files or the stable style changed
+    # That would cause the main workflow to "fail"
+    if:
+      github.event.workflow_run.event == 'pull_request' &&
+      contains(fromJSON('["success", "failure"]'), github.event.workflow_run.conclusion)
     permissions:
       pull-requests: write
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           persist-credentials: false
+
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        id: artifacts
+        with:
+          merge-multiple: true
+          pattern: ".*.pr-comment.md"
+          github-token: ${{ github.token }}
+          run-id: ${{ github.event.workflow_run.id }}
+
       - uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
         with:
           python-version: "3.13"
+          pip-version: "25.3"
+          pip-install: --group diff-shades-comment
 
-      - name: Install support dependencies
-        run: |
-          python -m pip install pip --upgrade
-          python -m pip install click packaging urllib3
+      - name: Get PR number
+        id: pr
+        run:
+          echo pr=$(gh pr list --search $sha --json number --jq ".[0].number") >>
+          "$GITHUB_OUTPUT"
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          sha: ${{ github.event.workflow_run.head_sha }}
 
       - name: Get details from initial workflow run
         id: metadata
+        run: |
+          python scripts/diff_shades_gha_helper.py comment-details \
+          $pr $run_id $(echo .*.pr-comment.md)
         env:
           GITHUB_TOKEN: ${{ github.token }}
-        run: >
-          python scripts/diff_shades_gha_helper.py comment-details
-          ${{github.event.workflow_run.id }}
+          pr: ${{ steps.pr.outputs.pr }}
+          run_id: ${{ github.event.workflow_run.id }}
 
       - name: Try to find pre-existing PR comment
-        if: steps.metadata.outputs.needs-comment == 'true'
         id: find-comment
         uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad
         with:
-          issue-number: ${{ steps.metadata.outputs.pr-number }}
+          issue-number: ${{ steps.pr.outputs.pr }}
           comment-author: "github-actions[bot]"
           body-includes: "diff-shades"
 
       - name: Create or update PR comment
-        if: steps.metadata.outputs.needs-comment == 'true'
         uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9
         with:
           comment-id: ${{ steps.find-comment.outputs.comment-id }}
-          issue-number: ${{ steps.metadata.outputs.pr-number }}
+          issue-number: ${{ steps.pr.outputs.pr }}
           body: ${{ steps.metadata.outputs.comment-body }}
           edit-mode: replace