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

permissions:
  contents: read

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'
    runs-on: ubuntu-latest
    name: Write comment to ping author about the pull request description
    steps:

      - name: Create comment about documentation
        if: github.event.label.name == 'Needs Documentation'
        uses: peter-evans/create-or-update-comment@v4
        with:
          token: ${{ secrets.GH_TOKEN_BOT }}
          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'

      - name: Create comment about changelog
        if: github.event.label.name == 'Changelog'
        uses: peter-evans/create-or-update-comment@v4
        with:
          token: ${{ secrets.GH_TOKEN_BOT }}
          issue-number: ${{ github.event.pull_request.number }}
          body: |
            @${{ github.event.pull_request.user.login }}

            This pull request has been tagged for the [changelog](https://www.qgis.org/en/site/forusers/visualchangelogs.html).

            * The description will be harvested so please provide a "nearly-ready" text for the final changelog
            * If possible, add a nice illustration of the feature. Only the **first** one in the description will be harvested (GIF accepted as well)
            * If you can, it's better to give credits to your sponsor, see below for different formats.

            You can edit the description.

            <details>
            <summary>Format available for credits</summary>
            <br />

            - `Funded by NAME`
            - `Funded by URL`
            - `Funded by NAME URL`
            - `Sponsored by NAME`
            - `Sponsored by URL`
            - `Sponsored by NAME URL`

            </details>

            Thank you!
          reactions: '+1'


  update-milestone:
    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' )
    # Update the milestone (if necessary)
    name: Update final milestone
    uses: ./.github/workflows/pr-auto-milestone.yml

  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 "label=${LABEL}" >> $GITHUB_OUTPUT

      # get the PR body
      - name: Get PR body as text
        id: get_pr_body
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_BODY: "${{ github.event.pull_request.body }}"
        run: |
          echo 'body<<EOF' >> $GITHUB_OUTPUT
          echo "$PR_BODY"  >> $GITHUB_OUTPUT
          echo 'EOF' >> $GITHUB_OUTPUT

      # 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 "commits=$(echo ${COMMITS_MESSAGES} | tr -d '\n' )" >> $GITHUB_OUTPUT

      # create the documentation issue
      - name: Create Documentation issue
        id: doc_issue
        uses: dacbd/create-issue-action@v2.0.0
        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@v4
        with:
          token: ${{ secrets.GH_TOKEN_BOT }}
          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'