docs/.github/workflows/readability.yml at f5df15a5c890d3ec0c598d1350cc4b4485d58b26 · github/docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
name: Readability report

# **What it does**: Analyzes readability of rendered content for changed Markdown files in pull requests
# **Why we have it**: We want to track and improve the readability of our documentation over time
# **Who does it impact**: Contributors and content writers

on:
  # pull_request:
  #   paths:
  #     - 'content/**/*.md'
  #     - 'data/reusables/**/*.md'
  # The pull_request trigger is currently disabled for testing purposes.
  # Re-enable this trigger when ready to run readability analysis automatically on PRs.
  workflow_dispatch:
    inputs:
      pull_request_number:
        description: 'Pull request number to analyze (for testing)'
        required: true
        type: number

permissions:
  contents: read
  pull-requests: write

jobs:
  readability-analysis:
    if: github.repository == 'github/docs-internal'
    runs-on: ubuntu-latest
    steps:
      - name: Check out repo with full history
        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
        with:
          fetch-depth: 0

      - name: Checkout PR for manual dispatch
        if: ${{ github.event_name == 'workflow_dispatch' }}
        run: |
          gh pr checkout ${{ inputs.pull_request_number }}
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - uses: ./.github/actions/node-npm-setup

      - uses: ./.github/actions/get-docs-early-access
        if: ${{ github.repository == 'github/docs-internal' }}
        with:
          token: ${{ secrets.DOCS_BOT_PAT_BASE }}

      - name: Get changed content files
        id: changed_files
        uses: ./.github/actions/get-changed-files
        with:
          files: 'content/**/*.md'
          # For workflow_dispatch, compare against main
          base: ${{ github.event_name == 'workflow_dispatch' && 'main' || '' }}

      - name: Disable Next.js telemetry
        run: npx next telemetry disable

      - name: Start server in the background
        if: ${{ steps.changed_files.outputs.filtered_changed_files }}
        run: npm start > /tmp/stdout.log 2> /tmp/stderr.log &

      - name: Run readability analysis
        if: ${{ steps.changed_files.outputs.filtered_changed_files }}
        env:
          CHANGED_FILES: ${{ steps.changed_files.outputs.filtered_changed_files }}
        run: npm run readability-report

      - name: Find existing readability comment
        if: ${{ steps.changed_files.outputs.filtered_changed_files }}
        uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad
        id: findComment
        with:
          issue-number: ${{ github.event_name == 'workflow_dispatch' && inputs.pull_request_number || github.event.number }}
          comment-author: 'github-actions[bot]'
          body-includes: '<!-- READABILITY_REPORT -->'

      - name: Read readability report
        if: ${{ steps.changed_files.outputs.filtered_changed_files }}
        id: read_report
        run: |
          if [ -f "readability-report.md" ]; then
            {
              echo 'report<<EOF'
              cat readability-report.md
              echo EOF
            } >> "$GITHUB_OUTPUT"
          fi

      - name: Create or update readability comment
        if: ${{ steps.changed_files.outputs.filtered_changed_files && steps.read_report.outputs.report }}
        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9
        with:
          comment-id: ${{ steps.findComment.outputs.comment-id }}
          issue-number: ${{ github.event_name == 'workflow_dispatch' && inputs.pull_request_number || github.event.number }}
          body: |
            <!-- READABILITY_REPORT -->
            ${{ steps.read_report.outputs.report }}
          edit-mode: replace

      - if: ${{ failure() }}
        name: Debug server outputs on errors
        run: |
          echo "____STDOUT____"
          cat /tmp/stdout.log || echo "No stdout log found"
          echo "____STDERR____"
          cat /tmp/stderr.log || echo "No stderr log found"