[misc] Add docs acknowledgement check (#4310)

adds a GitHub Actions workflow to enforce documentation requirements for pull requests, ensuring contributors acknowledge whether their changes need documentation updates or provide a link to a corresponding docs PR.

- Adds a new GitHub Actions workflow that validates documentation acknowledgement in PR descriptions
- Updates the PR template to include mandatory documentation checkboxes and URL field
- Implements validation logic to ensure exactly one documentation option is selected and verifies docs PR URLs when provided

.github/pull_request_template.md

@@ -12,6 +12,16 @@
 - [ ] Is a feature enhancement
 - [ ] It is a refactor
 - [ ] Created tests that fail without the change (if possible)
-- [ ] Extended the README / documentation, if necessary
 
 > By submitting this pull request, you confirm that you have read and agree to the terms of the [Contributor License Agreement](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT.md).
+
+## Documentation
+Select exactly one:
+
+- [ ] I added/updated documentation for this change
+- [ ] Documentation is **not needed** for this change (explain why)
+
+### Docs PR URL (required if "docs added" is checked)
+Paste the PR link from https://github.com/netbirdio/docs here:
+
+https://github.com/netbirdio/docs/pull/__

.github/workflows/docs-ack.yml

@@ -0,0 +1,94 @@
+name: Docs Acknowledgement
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  docs-ack:
+    name: Require docs PR URL or explicit "not needed"
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Read PR body
+        id: body
+        run: |
+          BODY=$(jq -r '.pull_request.body // ""' "$GITHUB_EVENT_PATH")
+          echo "body<<EOF" >> $GITHUB_OUTPUT
+          echo "$BODY" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Validate checkbox selection
+        id: validate
+        run: |
+          body='${{ steps.body.outputs.body }}'
+
+          added_checked=$(printf "%s" "$body" | grep -E '^- \[x\] I added/updated documentation' -i | wc -l | tr -d ' ')
+          noneed_checked=$(printf "%s" "$body" | grep -E '^- \[x\] Documentation is \*\*not needed\*\*' -i | wc -l | tr -d ' ')
+
+          if [ "$added_checked" -eq 1 ] && [ "$noneed_checked" -eq 1 ]; then
+            echo "::error::Choose exactly one: either 'docs added' OR 'not needed'."
+            exit 1
+          fi
+
+          if [ "$added_checked" -eq 0 ] && [ "$noneed_checked" -eq 0 ]; then
+            echo "::error::You must check exactly one docs option in the PR template."
+            exit 1
+          fi
+
+          if [ "$added_checked" -eq 1 ]; then
+            echo "mode=added" >> $GITHUB_OUTPUT
+          else
+            echo "mode=noneed" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Extract docs PR URL (when 'docs added')
+        if: steps.validate.outputs.mode == 'added'
+        id: extract
+        run: |
+          body='${{ steps.body.outputs.body }}'
+
+          # Strictly require HTTPS and that it's a PR in netbirdio/docs
+          # Examples accepted:
+          #   https://github.com/netbirdio/docs/pull/1234
+          url=$(printf "%s" "$body" | grep -Eo 'https://github\.com/netbirdio/docs/pull/[0-9]+' | head -n1 || true)
+
+          if [ -z "$url" ]; then
+            echo "::error::You checked 'docs added' but didn't include a valid HTTPS PR link to netbirdio/docs (e.g., https://github.com/netbirdio/docs/pull/1234)."
+            exit 1
+          fi
+
+          pr_number=$(echo "$url" | sed -E 's#.*/pull/([0-9]+)$#\1#')
+          echo "url=$url" >> $GITHUB_OUTPUT
+          echo "pr_number=$pr_number" >> $GITHUB_OUTPUT
+
+      - name: Verify docs PR exists (and is open or merged)
+        if: steps.validate.outputs.mode == 'added'
+        uses: actions/github-script@v7
+        id: verify
+        with:
+          pr_number: ${{ steps.extract.outputs.pr_number }}
+          script: |
+            const prNumber = parseInt(core.getInput('pr_number'), 10);
+            const { data } = await github.rest.pulls.get({
+              owner: 'netbirdio',
+              repo: 'docs',
+              pull_number: prNumber
+            });
+
+            // Allow open or merged PRs
+            const ok = data.state === 'open' || data.merged === true;
+            core.setOutput('state', data.state);
+            core.setOutput('merged', String(!!data.merged));
+            if (!ok) {
+              core.setFailed(`Docs PR #${prNumber} exists but is neither open nor merged (state=${data.state}, merged=${data.merged}).`);
+            }
+          result-encoding: string
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: All good
+        run: echo "Documentation requirement satisfied ✅"