docs(github-contributor): add evidence-loop, redaction, and merge-ready PR guidance

2026-03-05 20:34:10 +08:00
parent acde07ef09
commit b675ac6fee
4 changed files with 223 additions and 16 deletions
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -608,7 +608,7 @@
      "description": "Strategic guide for becoming an effective GitHub contributor. Covers opportunity discovery, project selection, high-quality PR creation, and reputation building. Use when looking to contribute to open-source projects, building GitHub presence, or learning contribution best practices",
      "source": "./",
      "strict": false,
-      "version": "1.0.0",
+      "version": "1.0.2",
      "category": "developer-tools",
      "keywords": [
        "github",
@@ -732,10 +732,10 @@
    },
    {
      "name": "tunnel-doctor",
-      "description": "Diagnoses and fixes conflicts between Tailscale and proxy/VPN tools (Shadowrocket, Clash, Surge) on macOS. Covers four conflict layers: route hijacking, HTTP proxy env var interception, system proxy bypass, and SSH ProxyCommand double tunneling. Includes SOP for remote development via SSH tunnels with proxy-safe Makefile patterns. Use when Tailscale ping works but SSH/HTTP times out, when browser returns 503 but curl works, when git push fails with failed to begin relaying via HTTP, when setting up Tailscale SSH to WSL instances, or when bootstrapping remote dev environments over Tailscale",
+      "description": "Diagnoses and fixes conflicts between Tailscale and proxy/VPN tools (Shadowrocket, Clash, Surge) on macOS. Covers five conflict layers: route hijacking, HTTP proxy env var interception, system proxy bypass, SSH ProxyCommand double tunneling, and VM/container proxy propagation. Includes an automated quick-diagnose script plus SOP for remote development via SSH tunnels with proxy-safe Makefile patterns. Use when Tailscale ping works but SSH/HTTP times out, when browser returns 503 but curl works, when local vanity domains fail behind proxy, when git push fails with failed to begin relaying via HTTP, when Docker pull times out behind TUN/VPN, when setting up Tailscale SSH to WSL instances, or when bootstrapping remote dev environments over Tailscale",
      "source": "./",
      "strict": false,
-      "version": "1.2.1",
+      "version": "1.3.0",
      "category": "developer-tools",
      "keywords": [
        "tailscale",
@@ -754,7 +754,8 @@
        "networking",
        "macos",
        "makefile",
-        "remote-development"
+        "remote-development",
+        "local-domain"
      ],
      "skills": [
        "./tunnel-doctor"
--- a/github-contributor/SKILL.md
+++ b/github-contributor/SKILL.md
@@ -7,6 +7,11 @@ description: Strategic guide for becoming an effective GitHub contributor. Cover

 Strategic guide for becoming an effective GitHub contributor and building your open-source reputation.

+## Prerequisites
+
+- Install GitHub CLI and verify availability: `gh --version`
+- Authenticate before running commands: `gh auth status || gh auth login`
+
 ## The Strategy

 **Core insight**: Many open-source projects have room for improvement. By contributing high-quality PRs, you:
@@ -102,7 +107,7 @@ Opportunity signals:

 ```bash
 # GitHub search for good first issues
-gh search issues "good first issue" --language=python --sort=created
+gh search issues "good first issue" --language=python --sort=created --state=open

 # Search by topic
 gh search repos "topic:cli" --sort=stars --limit=20
@@ -129,15 +134,23 @@ Pre-PR Checklist:
 **Title**: Clear, conventional format

 ```
-feat: Add support for YAML config files
-fix: Resolve race condition in connection pool
-docs: Update installation instructions for Windows
-refactor: Extract validation logic into separate module
+feat(config): add support for YAML config files
+fix(pool): resolve race condition in connection pool
+docs(readme): update installation instructions for Windows
+refactor(validation): extract validation logic into separate module
 ```

+**Evidence loop**: Prove the change with a reproducible fail -> fix -> pass loop.
+
+- Reproduce the failure with one command.
+- Apply the fix.
+- Rerun the exact same command and capture the passing output.
+- Compare baseline vs fixed vs reference behavior.
+- Redact local paths, secrets, tokens, and internal hostnames before posting logs or screenshots.
+
 **Description**: Structured and thorough

-```markdown
+````markdown
 ## Summary
 [What this PR does in 1-2 sentences]

@@ -148,12 +161,48 @@ refactor: Extract validation logic into separate module
 - [Change 1]
 - [Change 2]

+## Evidence Loop
+Command:
+```bash
+# Baseline (before fix)
+[command]
+
+# Fixed (after fix, same command)
+[command]
+```
+
+Raw output:
+```text
+[paste baseline output]
+```
+
+```text
+[paste fixed output]
+```
+
+## Comparison
+| Case | Command / Scenario | Result | Evidence |
+|------|--------------------|--------|----------|
+| Baseline | `[same command]` | Fail | [raw output block] |
+| Fixed | `[same command]` | Pass | [raw output block] |
+| Reference | [spec, issue, or main branch behavior] | Expected | [link or note] |
+
+## Sources/Attribution
+- [Issue, docs, or code references]
+
+## Risks
+- [Potential downside and impact]
+
+## Rollback Plan
+- Revert commit(s): [hash]
+- Restore previous behavior with: [command]
+
 ## Testing
 [How you tested this]

 ## Screenshots (if UI)
 [Before/After images]
-```
+````

 ### After Submitting

@@ -217,6 +266,9 @@ Contribution Workflow:
 - [ ] Comment on issue to claim
 - [ ] Fork and set up locally
 - [ ] Make focused changes
+- [ ] Run evidence loop (reproduce fail -> apply fix -> rerun same command pass)
+- [ ] Add baseline vs fixed vs reference comparison
+- [ ] Redact paths/secrets/internal hosts in logs and screenshots
 - [ ] Test thoroughly
 - [ ] Write clear PR description
 - [ ] Respond to review feedback
@@ -232,13 +284,13 @@ Contribution Workflow:
 gh repo fork owner/repo --clone

 # Create PR
-gh pr create --title "feat: ..." --body "..."
+gh pr create --title "feat(scope): ..." --body "..."

 # Check PR status
 gh pr status

 # View project issues
-gh issue list --repo owner/repo --label "good first issue"
+gh issue list --repo owner/repo --label "good first issue" --state=open
 ```

 ### Commit Message Format
--- a/github-contributor/references/communication_templates.md
+++ b/github-contributor/references/communication_templates.md
@@ -82,7 +82,7 @@ After:

 ### Feature Addition

-```markdown
+````markdown
 ## Summary

 Implements #[issue number]
@@ -112,7 +112,7 @@ result = new_feature(...)
 ## Migration Guide (if breaking)

 [Instructions for users to migrate]
-```
+````

 ### Documentation Update

@@ -133,6 +133,92 @@ Improves documentation for [area].
 [Screenshot or link to rendered docs]
 ```

+### Required PR Addendum
+
+Use this block in every PR description.
+
+````markdown
+## Evidence Loop
+
+Command:
+```bash
+# Baseline (before fix)
+[command]
+
+# Fixed (after fix, same command)
+[command]
+```
+
+Raw output:
+```text
+[baseline output]
+```
+
+```text
+[fixed output]
+```
+
+## Comparison (Baseline vs Fixed vs Reference)
+
+| Case | Command / Scenario | Result | Evidence |
+|------|--------------------|--------|----------|
+| Baseline | `[same command]` | Fail | [raw output block] |
+| Fixed | `[same command]` | Pass | [raw output block] |
+| Reference | [spec, issue, or main behavior] | Expected | [link or note] |
+
+## Sources/Attribution
+
+- [Issue, docs, benchmark source, or code reference]
+
+## Risks
+
+- [Risk and impact]
+
+## Rollback Plan
+
+- Revert commit(s): [hash]
+- Restore previous behavior with: [command]
+````
+
+## Reproducible PR Comment
+
+Use this template when maintainers ask for proof or rerun details.
+
+````markdown
+Validated with the same command before and after the fix.
+
+### Command
+```bash
+[command]
+```
+
+### Environment
+- OS: [name/version]
+- Runtime: [language/runtime + version]
+- Commit: [sha]
+- Runner: [local shell or CI job URL]
+
+### Baseline Output (before fix)
+```text
+[raw output]
+```
+
+### Fixed Output (after fix, same command)
+```text
+[raw output]
+```
+
+### Reference Output / Expected Behavior
+```text
+[spec output or expected result]
+```
+
+### Redaction Check
+- [x] Removed local absolute paths (for example, `/Users/...`)
+- [x] Removed tokens/secrets
+- [x] Removed internal URLs/hostnames
+````
+
 ## Responding to Reviews

 ### Accepting Feedback
--- a/github-contributor/references/pr_checklist.md
+++ b/github-contributor/references/pr_checklist.md
@@ -44,6 +44,20 @@ refactor/extract-validation-logic
 - [ ] No unnecessary changes (whitespace, imports)
 - [ ] Comments explain "why", not "what"

+### Evidence Loop
+
+- [ ] Reproduce the failure with one command and capture baseline output
+- [ ] Apply the fix
+- [ ] Rerun the exact same command and capture passing output
+- [ ] Add baseline vs fixed vs reference comparison
+
+### Redaction Gate
+
+- [ ] Remove local absolute paths (for example, `/Users/...`) from logs and screenshots
+- [ ] Remove secrets/tokens/API keys from logs and screenshots
+- [ ] Remove internal URLs/hostnames from logs and screenshots
+- [ ] Recheck every pasted block before submitting
+
 ### Documentation

 - [ ] README updated (if applicable)
@@ -59,6 +73,9 @@ refactor/extract-validation-logic
 - [ ] Testing approach
 - [ ] Screenshots (for UI changes)
 - [ ] Related issues linked
+- [ ] Sources/Attribution section added
+- [ ] Risks section added
+- [ ] Rollback Plan section added

 ## PR Title Format

@@ -76,7 +93,7 @@ chore(deps): update lodash to 4.17.21

 ## PR Description Template

-```markdown
+````markdown
 ## Summary

 Brief description of what this PR does.
@@ -93,6 +110,47 @@ Closes #123
 - Change 2
 - Change 3

+## Evidence Loop
+
+Command:
+```bash
+# Baseline (before fix)
+[command]
+
+# Fixed (after fix, same command)
+[command]
+```
+
+Raw output:
+```text
+[baseline output]
+```
+
+```text
+[fixed output]
+```
+
+## Comparison (Baseline vs Fixed vs Reference)
+
+| Case | Command / Scenario | Result | Evidence |
+|------|--------------------|--------|----------|
+| Baseline | `[same command]` | Fail | [raw output block] |
+| Fixed | `[same command]` | Pass | [raw output block] |
+| Reference | [spec, issue, or main behavior] | Expected | [link or note] |
+
+## Sources/Attribution
+
+- [Issue, docs, benchmark source, or code reference]
+
+## Risks
+
+- [Risk and impact]
+
+## Rollback Plan
+
+- Revert commit(s): [hash]
+- Restore previous behavior with: [command]
+
 ## Testing

 How did you test this change?
@@ -112,6 +170,16 @@ How did you test this change?
 - [ ] Tests pass
 - [ ] Documentation updated
 - [ ] Code follows project style
+````
+
+## Comparison Table Template
+
+```markdown
+| Case | Command / Scenario | Result | Evidence |
+|------|--------------------|--------|----------|
+| Baseline | `[same command]` | Fail | [raw output block] |
+| Fixed | `[same command]` | Pass | [raw output block] |
+| Reference | [spec, issue, or main behavior] | Expected | [link or note] |
 ```

 ## After Submitting