Check PR Documentation Compliance

Check PR Documentation Compliance

Analyzes pull requests from the last week to verify they include appropriate documentation updates. Identifies PRs that may need documentation but don't have it.

Overview

This skill helps ensure PRs include proper documentation by:

1. Listing recent PRs (last 7 days) for each repository
2. Checking if PRs have documentation updates
3. Independently checking wiki commits (may not be mentioned in PR)
4. Assessing whether documentation is needed
5. Flagging PRs that may need docs tagged

Quick Check

# List PRs from last week for inav firmware
cd inav
gh pr list --state all --search "created:>=$(date -d '7 days ago' +%Y-%m-%d)"

# List PRs from last week for configurator
cd inav-configurator
gh pr list --state all --search "created:>=$(date -d '7 days ago' +%Y-%m-%d)"

Documentation Check Workflow

Step 1: Get Recent PRs

For each repository (inav, inav-configurator), get PRs from the last week:

# Navigate to repo
cd inav  # or inav-configurator

# List PRs created in last 7 days
gh pr list --state all --search "created:>=$(date -d '7 days ago' +%Y-%m-%d)" --json number,title,url,state,author

# Get count
gh pr list --state all --search "created:>=$(date -d '7 days ago' +%Y-%m-%d)" | wc -l

Step 2: Fetch Recent Wiki Commits

CRITICAL: Check wiki commits independently - authors may update the wiki but not mention it in the PR.

Clone/​Update Wiki Repository

# For inav wiki
cd /​path/​to/​workspace

# Clone wiki if not already present
if [ ! -d "inav.wiki" ]; then
    git clone https://github.com/​iNavFlight/​inav.wiki.git
fi

cd inav.wiki
git pull origin master

# Get recent commits (last 7 days)
git log --since="7 days ago" --pretty=format:"%H|%an|%ae|%ai|%s" --all

Parse Wiki Commits

# Get wiki commits with details
git log --since="7 days ago" \
    --pretty=format:"%H|%an|%ae|%ai|%s" \
    --all > /​tmp/​wiki_commits.txt

# Example output format:
# abc123|John Doe|[email protected]|2025-12-21 14:30:00|Updated Navigation docs for PR #1234

Extract PR References from Wiki Commits

# Look for PR numbers in wiki commit messages
grep -oE "#[0-9]+" /​tmp/​wiki_commits.txt

# Or more detailed:
while IFS='|' read -r hash author email date message; do
    pr_refs=$(echo "$message" | grep -oE "#[0-9]+")
    if [ -n "$pr_refs" ]; then
        echo "Wiki commit $hash references: $pr_refs"
        echo "  Author: $author"
        echo "  Date: $date"
        echo "  Message: $message"
    fi
done < /​tmp/​wiki_commits.txt

Step 3: Check Each PR for Documentation

For each PR, check the following indicators of documentation:

A. Check Files Modified in PR

# Get list of files changed in PR
gh pr view <PR_NUMBER> --json files --jq '.files[].path'

# Check if any docs/ files were modified
gh pr view <PR_NUMBER> --json files --jq '.files[].path' | grep -i "docs/"

# Check for README updates
gh pr view <PR_NUMBER> --json files --jq '.files[].path' | grep -i "README"

# Check for wiki-related files
gh pr view <PR_NUMBER> --json files --jq '.files[].path' | grep -i "\.md$"

Documentation indicators (GOOD):

• Files in docs/ directory modified
• README files updated
• Markdown files added/​updated (may indicate docs)

B. Check PR Description for Links

# Get PR body/​description
gh pr view <PR_NUMBER> --json body --jq '.body'

# Look for PR references in description
gh pr view <PR_NUMBER> --json body --jq '.body' | grep -E "#[0-9]+"

# Look for wiki links
gh pr view <PR_NUMBER> --json body --jq '.body' | grep -iE "wiki|documentation"

Documentation indicators (GOOD):

• Links to other PRs (e.g., "Docs in #1234")
• Links to wiki pages or commits
• Mentions of "documentation", "wiki", "docs updated"
• References like "See inavflight/​inav-configurator#5678"

C. Check PR Comments

# Get PR comments
gh api repos/​inavflight/​inav/​pulls/<PR_NUMBER>/​comments --jq '.[].body'

# Or for configurator
gh api repos/​inavflight/​inav-configurator/​pulls/<PR_NUMBER>/​comments --jq '.[].body'

# Search for documentation mentions
gh api repos/​inavflight/​inav/​pulls/<PR_NUMBER>/​comments --jq '.[].body' | grep -iE "wiki|docs|documentation"

Documentation indicators (GOOD):

• Comments linking to wiki updates
• Comments linking to documentation PRs
• Maintainer confirmation of docs

D. NEW: Cross-Reference with Wiki Commits

Check if wiki was updated by same author around the same time:

# Get PR details
PR_NUM=1234
pr_author=$(gh pr view $PR_NUM --json author --jq '.author.login')
pr_merged=$(gh pr view $PR_NUM --json mergedAt --jq '.mergedAt')
pr_created=$(gh pr view $PR_NUM --json createdAt --jq '.createdAt')

# Search wiki commits by author
cd inav.wiki
git log --since="7 days ago" --author="$pr_author" --pretty=format:"%ai|%s"

# Search wiki commits mentioning this PR number
git log --since="7 days ago" --grep="#$PR_NUM" --pretty=format:"%H|%an|%ai|%s"

# Search wiki commits in time window (±2 days of PR merge)
# This catches wiki updates made around the same time as the PR
git log --since="$(date -d "$pr_merged - 2 days" +%Y-%m-%d)" \
        --until="$(date -d "$pr_merged + 2 days" +%Y-%m-%d)" \
        --author="$pr_author" \
        --pretty=format:"%ai|%s"

Wiki matching strategies:

1. Direct PR reference: Wiki commit message mentions "#1234"
2. Author + time match: Same author committed to wiki within ±2 days of PR
3. Topic match: Wiki commit message mentions related keywords from PR title

# Example: Check if wiki commit topics match PR
pr_title=$(gh pr view $PR_NUM --json title --jq '.title')

# Extract key terms from PR title (e.g., "GPS", "navigation", "OSD")
key_terms=$(echo "$pr_title" | grep -oE "[A-Z]{2,}|navigation|telemetry|OSD|CLI" | tr '\n' '|' | sed 's/|$//')

# Search wiki for those terms
cd inav.wiki
git log --since="7 days ago" --grep="$key_terms" -i --pretty=format:"%H|%an|%ai|%s"

Step 4: Assess If Documentation Is Needed

If no documentation indicators found, evaluate whether docs are likely needed based on:

Changes Likely Needing Documentation:

Firmware (inav):

• New features or modes
• New CLI commands or settings
• New MSP messages
• Changes to flight behavior
• New sensor support
• Navigation changes
• Changes affecting users (not just internal refactoring)

Configurator:

• New UI features or tabs
• New settings/​configuration options
• Changes to user workflows
• New tooltips or help text
• Feature additions visible to users

Changes NOT Needing Documentation:

• Internal refactoring (no user-visible changes)
• Code cleanup or formatting
• Dependency updates (unless user-facing)
• Build system changes (unless affecting developers)
• Test additions/​fixes
• Bug fixes (minor, no behavior change)
• CI/​workflow updates

Step 5: Check File Contents for Clues

# View the actual diff to understand changes
gh pr diff <PR_NUMBER>

# Check specific files
gh pr diff <PR_NUMBER> | grep "^+" | head -20

Look for:

• New CLI commands (cliXXX, pgRegistry)
• New MSP messages (MSP_, MSP2_)
• New settings structures
• UI component additions
• Feature flag additions

Step 6: Generate Report

Create a summary report with:

## PR Documentation Check - YYYY-MM-DD

### Repository: inav

#### PRs with Documentation ✅

- #1234 - "Add new flight mode" - docs/ files modified
- #1235 - "Update GPS settings" - links to wiki PR
- #1236 - "Add telemetry feature" - wiki commit found (abc123, same author, ±1 day)
- #1237 - "Fix OSD layout" - wiki commit references #1237

#### PRs Needing Documentation Review ⚠️

- #1238 - "Add new CLI command 'set gps_mode'"
  - Reason: New user-facing CLI command, no docs found
  - Wiki check: No commits by author in time window
  - Action needed: Tag as "documentation needed"?

- #1239 - "Add RTH altitude preset"
  - Reason: New user-visible feature, no docs found
  - Wiki check: No related wiki commits found
  - Action needed: Tag as "documentation needed"?

#### PRs Not Needing Documentation ℹ️

- #1240 - "Refactor PID controller code" - Internal refactoring only
- #1241 - "Update GitHub Actions workflow" - CI changes only
- #1242 - "Fix typo in comment" - Code comment fix

### Repository: inav-configurator

(Similar structure)

### Wiki Commits Summary

**Total wiki commits (last 7 days):** 12

**Commits with PR references:**
- abc123 - "Updated Navigation.md for #1234" (matched to PR #1234 ✅)
- def456 - "OSD documentation #1237" (matched to PR #1237 ✅)

**Commits without PR references (by author/​time):**
- ghi789 - "Updated telemetry docs" by user123, 2025-12-22 (matched to PR #1236 by author/​time ✅)

**Unmatched wiki commits:**
- jkl012 - "Fix typo in GPS.md" (minor fix, no PR needed)

Complete Workflow Script

Here's a complete workflow you can follow:

#!/​bin/​bash

# Check PR documentation for last week

echo "=== PR Documentation Check ==="
echo "Date: $(date)"
echo ""

# Step 1: Update wiki repositories
echo "=== Updating Wiki Repositories ==="
for wiki_repo in inav.wiki inav-configurator.wiki; do
    if [ -d "$wiki_repo" ]; then
        cd "$wiki_repo"
        git pull origin master
        cd ..
    else
        if [ "$wiki_repo" = "inav.wiki" ]; then
            git clone https://github.com/​iNavFlight/​inav.wiki.git
        elif [ "$wiki_repo" = "inav-configurator.wiki" ]; then
            git clone https://github.com/​iNavFlight/​inav-configurator.wiki.git
        fi
    fi
done
echo ""

# Step 2: Get wiki commits
echo "=== Recent Wiki Commits ==="
cd inav.wiki
echo "## inav.wiki commits (last 7 days):"
git log --since="7 days ago" --pretty=format:"%H|%an|%ai|%s" --all > /​tmp/​inav_wiki_commits.txt
cat /​tmp/​inav_wiki_commits.txt
echo ""
cd ..

cd inav-configurator.wiki
echo "## inav-configurator.wiki commits (last 7 days):"
git log --since="7 days ago" --pretty=format:"%H|%an|%ai|%s" --all > /​tmp/​configurator_wiki_commits.txt
cat /​tmp/​configurator_wiki_commits.txt
echo ""
cd ..

# Step 3: Check PRs in each repo
for repo in inav inav-configurator; do
    echo "### Repository: $repo"
    echo ""

    cd "$repo"

    # Determine wiki file
    if [ "$repo" = "inav" ]; then
        wiki_commits="/​tmp/​inav_wiki_commits.txt"
    else
        wiki_commits="/​tmp/​configurator_wiki_commits.txt"
    fi

    # Get PRs from last week
    prs=$(gh pr list --state all --search "created:>=$(date -d '7 days ago' +%Y-%m-%d)" --json number --jq '.[].number')

    if [ -z "$prs" ]; then
        echo "No PRs in last 7 days"
        echo ""
        cd ..
        continue
    fi

    for pr in $prs; do
        echo "#### PR #$pr"

        # Get PR details
        pr_data=$(gh pr view $pr --json title,author,mergedAt,createdAt,state)
        title=$(echo "$pr_data" | jq -r '.title')
        author=$(echo "$pr_data" | jq -r '.author.login')
        merged=$(echo "$pr_data" | jq -r '.mergedAt')
        created=$(echo "$pr_data" | jq -r '.createdAt')
        state=$(echo "$pr_data" | jq -r '.state')

        echo "Title: $title"
        echo "Author: $author"
        echo "State: $state"

        has_docs=false

        # Check for docs files in PR
        docs_files=$(gh pr view $pr --json files --jq '.files[].path' | grep -iE "docs/|README|\.md$" || true)
        if [ -n "$docs_files" ]; then
            echo "✅ Has documentation files in PR"
            echo "$docs_files"
            has_docs=true
        fi

        # Check PR body for references
        body=$(gh pr view $pr --json body --jq '.body')
        wiki_refs=$(echo "$body" | grep -iE "wiki|#[0-9]+|documentation" || true)
        if [ -n "$wiki_refs" ]; then
            echo "✅ Has documentation references in PR description"
            has_docs=true
        fi

        # Check wiki commits for PR reference
        wiki_pr_refs=$(grep "#$pr" "$wiki_commits" || true)
        if [ -n "$wiki_pr_refs" ]; then
            echo "✅ Wiki commit references this PR:"
            echo "$wiki_pr_refs"
            has_docs=true
        fi

        # Check wiki commits by same author in time window
        if [ "$state" = "MERGED" ] && [ "$merged" != "null" ]; then
            # Check ±2 days from merge
            wiki_author_commits=$(grep "$author" "$wiki_commits" || true)
            if [ -n "$wiki_author_commits" ]; then
                echo "✅ Wiki commits by same author (check time proximity):"
                echo "$wiki_author_commits"
                has_docs=true
            fi
        fi

        if [ "$has_docs" = false ]; then
            echo "⚠️ No documentation found - needs review"
        fi

        echo ""
    done

    cd ..
done

echo "=== Check Complete ==="

Wiki Commit Matching Logic

Priority 1: Direct PR Reference

# Wiki commit message contains "#1234"
grep "#$PR_NUM" /​tmp/​wiki_commits.txt

Confidence: HIGH - Explicit link

Priority 2: Author + Time Window

# Same author, within ±2 days of PR merge
pr_merge_date="2025-12-22"
author="john_doe"

# Check if any commits match
git log --since="$(date -d "$pr_merge_date - 2 days" +%Y-%m-%d)" \
        --until="$(date -d "$pr_merge_date + 2 days" +%Y-%m-%d)" \
        --author="$author" \
        --pretty=format:"%ai|%s"

Confidence: MEDIUM - Likely related if timing matches

Priority 3: Topic/​Keyword Match

# PR title: "Add GPS altitude hold feature"
# Look for wiki commits mentioning "GPS" or "altitude"

pr_title="Add GPS altitude hold feature"
keywords=$(echo "$pr_title" | grep -oE "[A-Za-z]{3,}" | sort -u | tr '\n' '|' | sed 's/|$//')

git log --since="7 days ago" \
        --grep="$keywords" -i \
        --pretty=format:"%H|%an|%ai|%s"

Confidence: LOW - May be coincidental, needs human review

Implementation Notes

Wiki Repository Locations

# Clone wiki repos if not present
git clone https://github.com/​iNavFlight/​inav.wiki.git
git clone https://github.com/​iNavFlight/​inav-configurator.wiki.git

# Standard locations in workspace
~/​Documents/​planes/​inavflight/​inav.wiki/
~/​Documents/​planes/​inavflight/​inav-configurator.wiki/

Date Calculation

Different systems may need different date commands:

# Linux
date -d '7 days ago' +%Y-%m-%d
date -d "$some_date - 2 days" +%Y-%m-%d

# macOS
date -v-7d +%Y-%m-%d
date -j -f "%Y-%m-%d" "$some_date" -v-2d +%Y-%m-%d

Handling Email vs. GitHub Username

Wiki commits may use email addresses while GitHub PRs use usernames:

# Get both from PR
gh pr view $PR_NUM --json author --jq '.author.login'  # GitHub username
gh pr view $PR_NUM --json commits --jq '.commits[0].commit.author.email'  # Email from commit

# Search wiki by either
git log --author="username_or_email"

Common Scenarios

Scenario 1: PR with docs/ files

PR #1234 - "Add GPS altitude hold"
Files changed:
  - src/​main/​navigation/​navigation_pos_estimator.c
  - docs/​Navigation.md ✅

Result: ✅ Documentation included
Action: None needed

Scenario 2: PR with Wiki commit reference

PR #1235 - "Add new telemetry fields"
Files changed:
  - src/​main/​telemetry/​crsf.c
Wiki commits:
  - abc123: "Updated Telemetry.md for #1235" ✅

Result: ✅ Wiki updated and linked
Action: None needed

Scenario 3: PR with Wiki commit by author (no reference)

PR #1236 - "Add OSD element" by user_alice
Merged: 2025-12-22
Files changed:
  - src/​main/​io/​osd.c
Wiki commits:
  - def456: "Updated OSD.md" by user_alice, 2025-12-22 ✅

Result: ✅ Wiki likely updated (author/​time match)
Action: Verify this is the related update

Scenario 4: Feature PR without any docs

PR #1237 - "Add new CLI command"
Files changed:
  - src/​main/​cli/​settings.c
No docs/ changes, no wiki references
Wiki commits: None by author in time window ⚠️

Result: ⚠️ Likely needs documentation
Action: Ask user to tag as "documentation needed"

Scenario 5: Refactoring PR

PR #1238 - "Refactor PID loop structure"
Files changed:
  - src/​main/​flight/​pid.c (internal refactoring)
No user-visible changes ℹ️

Result: ℹ️ No documentation needed
Action: Note as internal change only

Tips for Effective Checking

1. Always check wiki independently - Don't rely on PR mentions
2. Match by author + time - Often more reliable than PR references
3. Read PR titles carefully - Often indicate if user-facing
4. Check PR labels - May already be tagged
5. Look at file paths - src/​main/ often user-facing, lib/ usually not
6. Search for keywords - "CLI", "MSP", "OSD", "setting" indicate user features
7. Check wiki commit dates - May be before OR after PR merge

Output Format

Generate a structured report for the user:

# PR Documentation Check Report
**Date:** 2025-12-28
**Period:** Last 7 days

## Summary
- Total PRs checked: 15
- PRs with documentation: 8 ✅
  - With docs/ files: 3
  - With PR-referenced wiki commits: 2
  - With author-matched wiki commits: 3
- PRs needing doc review: 4 ⚠️
- PRs not needing docs: 3 ℹ️

## Wiki Activity Summary
- Total wiki commits: 12
- Wiki commits with PR refs: 5 (matched to PRs)
- Wiki commits matched by author/​time: 3
- Unmatched wiki commits: 4 (typo fixes, minor updates)

## Detailed Findings

[Details for each PR category]

## Recommended Actions

[List of PRs to tag, with reasons]

Related Skills

• pr-review - Review PR code and comments
• git-workflow - Manage git operations for PRs
• wiki-search - Search wiki for related documentation
• check-builds - Verify PR builds pass

---

Note: This is a manager skill for tracking documentation compliance. The manager should run this periodically to ensure PRs include appropriate documentation.