|
| 1 | +# Setup and Usage Guide |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This repository automatically tracks all merged Pull Requests using GitHub Actions. Every time a PR is merged, the workflow automatically updates the README.md file with the PR details. |
| 6 | + |
| 7 | +## How the Automation Works |
| 8 | + |
| 9 | +### Trigger |
| 10 | +The automation is triggered when a Pull Request is closed. It only runs when the PR is actually merged (not just closed without merging). |
| 11 | + |
| 12 | +### Workflow Steps |
| 13 | + |
| 14 | +1. **Detection**: GitHub Actions detects when a PR is merged |
| 15 | +2. **Checkout**: The workflow checks out the repository code |
| 16 | +3. **Data Extraction**: Extracts the following information: |
| 17 | + - PR Number |
| 18 | + - PR Title |
| 19 | + - PR URL |
| 20 | + - Merge Date (Year) |
| 21 | + - Labels/Tags |
| 22 | +4. **Update README**: Inserts a new row in the README table with the PR information |
| 23 | +5. **Commit & Push**: Automatically commits and pushes the changes back to the repository |
| 24 | + |
| 25 | +### Data Processing |
| 26 | + |
| 27 | +- **Year Extraction**: Parses the merge timestamp to get the year |
| 28 | +- **Label Processing**: Converts label array to comma-separated string |
| 29 | +- **Special Character Handling**: Escapes special characters (like `|`) in PR titles |
| 30 | +- **Table Formatting**: Maintains proper markdown table format |
| 31 | + |
| 32 | +## File Structure |
| 33 | + |
| 34 | +``` |
| 35 | +. |
| 36 | +├── README.md # Main file with PR tracking table |
| 37 | +├── .github/ |
| 38 | +│ └── workflows/ |
| 39 | +│ └── update-pr-list.yml # GitHub Actions workflow |
| 40 | +└── SETUP.md # This file |
| 41 | +``` |
| 42 | + |
| 43 | +## Configuration |
| 44 | + |
| 45 | +### Required Permissions |
| 46 | + |
| 47 | +The workflow needs the following permissions (already configured): |
| 48 | +- `contents: write` - To commit and push changes to README.md |
| 49 | +- `pull-requests: read` - To read PR details |
| 50 | + |
| 51 | +### Repository Settings |
| 52 | + |
| 53 | +1. Go to repository **Settings** → **Actions** → **General** |
| 54 | +2. Under **Workflow permissions**, ensure: |
| 55 | + - "Read and write permissions" is selected |
| 56 | + - "Allow GitHub Actions to create and approve pull requests" is checked (optional) |
| 57 | + |
| 58 | +## Customization |
| 59 | + |
| 60 | +### Modifying the Table Format |
| 61 | + |
| 62 | +To change the table columns or format, edit the workflow file: |
| 63 | + |
| 64 | +```yaml |
| 65 | +# In .github/workflows/update-pr-list.yml |
| 66 | +# Modify the NEW_ROW variable to change table format |
| 67 | +NEW_ROW="| #${PR_NUMBER} | ${SAFE_TITLE} | [Link](${PR_URL}) | ${YEAR} | ${TAGS} |" |
| 68 | +``` |
| 69 | + |
| 70 | +### Adding More PR Information |
| 71 | + |
| 72 | +You can add more fields from the GitHub event payload. Available fields include: |
| 73 | +- `github.event.pull_request.user.login` - PR author |
| 74 | +- `github.event.pull_request.merged_by.login` - Who merged the PR |
| 75 | +- `github.event.pull_request.base.ref` - Base branch |
| 76 | +- `github.event.pull_request.head.ref` - Head branch |
| 77 | + |
| 78 | +Example to add author: |
| 79 | +```yaml |
| 80 | +env: |
| 81 | + PR_AUTHOR: ${{ github.event.pull_request.user.login }} |
| 82 | +``` |
| 83 | +
|
| 84 | +### Changing the Sort Order |
| 85 | +
|
| 86 | +Currently, new PRs are added at the top of the list. To add them at the bottom: |
| 87 | +
|
| 88 | +Change: |
| 89 | +```bash |
| 90 | +sed -i "/<!-- PR_LIST_START -->/a ${NEW_ROW}" README.md |
| 91 | +``` |
| 92 | + |
| 93 | +To: |
| 94 | +```bash |
| 95 | +sed -i "/<!-- PR_LIST_END -->/i ${NEW_ROW}" README.md |
| 96 | +``` |
| 97 | + |
| 98 | +## Testing |
| 99 | + |
| 100 | +### Local Testing |
| 101 | + |
| 102 | +You can test the workflow logic locally using the test script: |
| 103 | + |
| 104 | +```bash |
| 105 | +# Set environment variables |
| 106 | +export PR_NUMBER=123 |
| 107 | +export PR_TITLE="Test PR" |
| 108 | +export PR_URL="https://github.com/owner/repo/pull/123" |
| 109 | +export PR_MERGED_AT="2025-11-17T07:00:00Z" |
| 110 | +export PR_LABELS='[{"name": "bug"}, {"name": "critical"}]' |
| 111 | + |
| 112 | +# Run the workflow commands |
| 113 | +YEAR=$(echo "$PR_MERGED_AT" | cut -d'-' -f1) |
| 114 | +TAGS=$(echo "$PR_LABELS" | jq -r '[.[].name] | join(", ")') |
| 115 | +# ... etc |
| 116 | +``` |
| 117 | + |
| 118 | +### Workflow Testing |
| 119 | + |
| 120 | +1. Create a test branch |
| 121 | +2. Make some changes and open a PR |
| 122 | +3. Merge the PR |
| 123 | +4. Check if the README.md is updated automatically |
| 124 | + |
| 125 | +### Backfilling Historical PRs |
| 126 | + |
| 127 | +To populate the table with your previously merged PRs from other repositories: |
| 128 | + |
| 129 | +#### Option 1: Using the Backfill Script (Requires GitHub CLI) |
| 130 | + |
| 131 | +```bash |
| 132 | +# Install GitHub CLI if not already installed |
| 133 | +# Visit: https://cli.github.com/ |
| 134 | + |
| 135 | +# Authenticate with GitHub |
| 136 | +gh auth login |
| 137 | + |
| 138 | +# Run the backfill script |
| 139 | +./scripts/backfill-historical-prs.sh |
| 140 | +``` |
| 141 | + |
| 142 | +The script will: |
| 143 | +1. Search for all your merged PRs across GitHub |
| 144 | +2. Extract PR details (number, title, URL, year, labels, repository) |
| 145 | +3. Add them to the README table |
| 146 | +4. Create a backup (README.md.backup) before making changes |
| 147 | + |
| 148 | +#### Option 2: Manual Addition |
| 149 | + |
| 150 | +You can manually add historical PRs by editing README.md: |
| 151 | + |
| 152 | +```markdown |
| 153 | +<!-- PR_LIST_START --> |
| 154 | +| #123 | My PR Title (owner/repo) | [Link](url) | 2024 | bug, feature | |
| 155 | +<!-- PR_LIST_END --> |
| 156 | +``` |
| 157 | + |
| 158 | +**Important**: Always add new entries between the `<!-- PR_LIST_START -->` and `<!-- PR_LIST_END -->` markers. |
| 159 | + |
| 160 | +## Troubleshooting |
| 161 | + |
| 162 | +### Workflow Not Running |
| 163 | + |
| 164 | +1. Check if the workflow file is in the correct location: `.github/workflows/update-pr-list.yml` |
| 165 | +2. Verify repository permissions (Settings → Actions → General) |
| 166 | +3. Check the Actions tab for any errors |
| 167 | + |
| 168 | +### README Not Updated |
| 169 | + |
| 170 | +1. Check the workflow logs in the Actions tab |
| 171 | +2. Verify that the PR was actually merged (not just closed) |
| 172 | +3. Ensure the markers `<!-- PR_LIST_START -->` and `<!-- PR_LIST_END -->` exist in README.md |
| 173 | + |
| 174 | +### Permission Errors |
| 175 | + |
| 176 | +If you see permission errors: |
| 177 | +1. Go to Settings → Actions → General |
| 178 | +2. Enable "Read and write permissions" |
| 179 | +3. Re-run the workflow |
| 180 | + |
| 181 | +## Best Practices |
| 182 | + |
| 183 | +1. **Don't manually edit** the PR list section between the markers |
| 184 | +2. **Keep the markers** (`<!-- PR_LIST_START -->` and `<!-- PR_LIST_END -->`) intact |
| 185 | +3. **Use meaningful PR titles** as they will appear in the table |
| 186 | +4. **Add relevant labels** to PRs for better categorization |
| 187 | +5. **Review the automated commit** after merging to ensure correct formatting |
| 188 | + |
| 189 | +## Example Workflow |
| 190 | + |
| 191 | +Here's what happens when you merge a PR: |
| 192 | + |
| 193 | +1. You merge PR #5 titled "Add new feature" with labels "enhancement" and "feature" |
| 194 | +2. GitHub Actions workflow is triggered |
| 195 | +3. Workflow extracts: PR #5, title, URL, year 2025, tags "enhancement, feature" |
| 196 | +4. A new row is added to the README table: |
| 197 | + ``` |
| 198 | + | #5 | Add new feature | [Link](url) | 2025 | enhancement, feature | |
| 199 | + ``` |
| 200 | +5. Changes are committed and pushed automatically |
| 201 | +6. README is updated instantly |
| 202 | + |
| 203 | +## Support |
| 204 | + |
| 205 | +For issues or questions: |
| 206 | +1. Check the workflow logs in the Actions tab |
| 207 | +2. Review this documentation |
| 208 | +3. Check GitHub Actions documentation for more details on workflows |
0 commit comments