pr-needs-documentation.yml

name: 📖 PR needs documentation

# a message will be added to the PR to ping the author about her/his responsibility to handle the documentation issue
# an issue is automatically created in the QGIS-Documentation repository when the PR gets merged

on:
  pull_request_target:
    types:
      - opened
      - closed
      - labeled

jobs:
  ping-author-message:
    permissions:
      issues: write  # for peter-evans/create-or-update-comment to create or update comment
      pull-requests: write  # for peter-evans/create-or-update-comment to create or update comment
    if: github.event.action != 'closed' && github.event.label.name == 'Needs Documentation'
    runs-on: ubuntu-latest
    name: Write comment to ping author about the future creation of an issue in docs
    steps:

      # write comment to ping the PR author
      - name: Create comment
        uses: peter-evans/create-or-update-comment@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.pull_request.number }}
          body: |
            @${{ github.event.pull_request.user.login }}
            This pull request has been tagged as **requiring documentation**.

            A documentation ticket will be opened at https://github.com/qgis/QGIS-Documentation **when this PR is merged**.

            **Please update the description** (not the comments) with helpful description and screenshot to help the work from documentors.
            Also, any commit having [needs-doc] or [Needs Documentation] in will see its message pushed to the issue, so please be as verbose as you can.

            Thank you!
          reactions: 'rocket'


  create-doc-issue:
    if: github.event.pull_request.merged && ( ( github.event.action == 'closed' && contains( github.event.pull_request.labels.*.name, 'Needs Documentation') ) || github.event.label.name == 'Needs Documentation' )
    runs-on: ubuntu-latest
    name: Create issue on doc repo for labeled issue
    steps:

      # transform the milestone (e.g. 3.10.4) to a doc label (3.10)
      - name: QGIS milestone to Doc label
        id: milestone2label
        env:
          MILESTONE: ${{ github.event.pull_request.milestone.title }}
        run: |
          LABEL=$(sed -r 's/^([[:digit:]]\.[[:digit:]]+)(\.[[:digit:]]+)?$/\1/' <<< ${MILESTONE})
          echo ${LABEL}
          echo "::set-output name=label::${LABEL}"
            # get the PR body

      # get the PR body
      - name: Get PR body as JSON
        id: get_pr_info
        uses: octokit/request-action@v2.x
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          route: GET /repos/qgis/QGIS/pulls/:pull_number
          pull_number: ${{ github.event.pull_request.number }}

      # extract body from json output
      - name: Get PR body as text
        id: get_pr_body
        uses: gr2m/get-json-paths-action@v1.x
        with:
          json: ${{ steps.get_pr_info.outputs.data }}
          body: "body"

      # get commits from the PR
      - name: Get PR commits
        uses: octokit/request-action@v2.x
        id: get_pr_commits
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          route: GET /repos/qgis/QGIS/pulls/:pull_number/commits
          pull_number: ${{ github.event.pull_request.number }}

      # extracts the matching commits
      - name: Filter commits with \[needs?.doc(umentation)?s?\]
        id: filtered_commits
        env:
          JSON_DATA: ${{ steps.get_pr_commits.outputs.data }}
        run: |
          COMMITS_MESSAGES=$(echo ${JSON_DATA} | jq '.[].commit.message | select( . |test("\\[(feature|needs?.doc(umentation)?s?)\\]"; "i")) | sub("\\[needs?.doc(umentation)?s?\\]"; "\n\n\n\n"; "i")')
          echo "::set-output name=commits::$(echo ${COMMITS_MESSAGES} | tr -d '\n' )"

      # create the documentation issue
      - name: Create Documentation issue
        id: doc_issue
        uses: maxkomarychev/oction-create-issue@v0.7.1
        with:
          token: ${{ secrets.GH_TOKEN_BOT }}
          owner: qgis
          repo: QGIS-Documentation
          title: ${{ format('{0} (Request in QGIS)', github.event.pull_request.title) }}
          # do not modify the QGIS version, an action automatically creates a label in the doc repo
          # this is not possible to set labels directly due to security reasons
          # the token is in clear, so no rights are given to qgis-bot
          body: |
            ### Request for documentation
            From pull request QGIS/qgis#${{ github.event.pull_request.number }}
            Author: @${{ github.event.pull_request.user.login }}
            QGIS version: ${{ steps.milestone2label.outputs.label }}

            **${{ github.event.pull_request.title }}**

            ### PR Description:
            ${{ steps.get_pr_body.outputs.body }}

            ### Commits tagged with [need-docs] or [FEATURE]
            ${{ steps.filtered_commits.outputs.commits }}

      # write comment to ping the PR author
      - name: Create comment
        uses: peter-evans/create-or-update-comment@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.pull_request.number }}
          body: |
            @${{ github.event.pull_request.user.login }}
            A documentation ticket has been opened at https://github.com/qgis/QGIS-Documentation/issues/${{ steps.doc_issue.outputs.number }}
            It is **your** responsibility to visit this ticket and add as much detail as possible for the documentation team to correctly document this change.
            Thank you!
          reactions: 'rocket'