docs: contributor guide improvements proposal#702
Conversation
🔒 Security Review: PR #702 Contributor Guide ImprovementsSummaryReviewed the contributor guide proposal with focus on SECURITY.md changes, .squad directory guidance, and issue template security implications. Overall: APPROVED with strong recommendations on CI hardening and information disclosure considerations. ✅ Approved Areas1. SECURITY.md Typo Fix (P3)
2. .squad/ Directory Explainer (P1)
3. Issue Templates (P1)
4. CI Hardening Changes
|
✅ DevRel Review: Contributor Guide Improvements ProposalReviewer: PAO (DevRel) | Context: Contributor experience, OSS best practices OverviewFlight's proposal is excellent — it's data-driven, prioritized, scoped, and directly addresses real friction patterns. This is exactly the kind of audit-first approach that prevents premature optimization and fixes actual problems. Strengths1. Empirical Foundation ⭐
This matters: Proposals grounded in data = higher adoption and trust 2. Clear Prioritization
This matters: Prevents "nice to have" scope creep 3. Contributor-Centric LanguageThe proposal speaks from contributor POV:
This is important for DevRel: It shows empathy and reframes as enabling success, not policing contributions. Detailed Feedback✅ Items 2a–2f (GitHub UX / Docs)2a. Issue Templates — STRONG
2b. Good First Issue Curation — ALIGNED
2c. .squad/ Explainer — CRITICAL & MISSINGExcellent catch. The proposed text is clear:
2d. CODE_OF_CONDUCT.md — STANDARD & TRUSTED
2e. Contributor FAQ — HIGH IMPACTTopics are perfect:
2f. README Contributing Section — DISCOVERY WINThe emoji-led "Ways to Contribute" format is inviting and clear. Good job on:
|
| Practice | Status | Notes |
|---|---|---|
| Issue templates (structured data) | ✅ Proposed | YAML format enforces required fields |
| CODE_OF_CONDUCT (trust signal) | ✅ Proposed | Contributor Covenant v2.1 (industry standard) |
| Good first issues (on-ramp) | ✅ Proposed | Workflow doc prevents decay |
| FAQ/troubleshooting (reduce friction) | ✅ Proposed | Targets real pain points |
| Branch strategy clarity | ✅ Proposed | Bold callout in README + FAQ |
| Contributor recognition | ✅ Exists | CONTRIBUTORS.md already in place |
| Labels for contribution categories | ✅ Proposed | Label consolidation (see Open Q3) |
Recommendation
✅ APPROVE the contributor guide proposal (items 2a–2f + 2g)
This should ship. The audit is solid, the priorities are clear, and success metrics are measurable.
🔄 SEPARATE the CI hardening changes (into a sibling PR)
The CI improvements (setup-squad-node, rate limits, registry checks) are good, but they belong in a focused "CI Hardening" PR with their own justification.
�� Next Steps for Implementation
- This PR merges as approved proposal → signals commitment to contributor experience
- Follow-up sprint (1 week): Implement 2a+2c+2e+2f+2g (4 hrs estimated)
- Parallel sprint: 2b (good first issue curation — requires issue audit)
- Separate PR: CI hardening (I don't see a tool called task in github copilot #9, Copilot client parity: Squad works fully only on GitHub Copilot CLI #10 health checks + composite action)
- Open question follow-up: Address Q1, Q2, Q3 in team sync
Final Thoughts
This proposal raises the bar for contributor experience in a thoughtful way. The data-driven approach and clear execution plan show that Flight understands both the problem and the solution.
The goal—"external contributors can be successful using only the docs"—is worth investing in. Even small improvements here compound: better contributions → less triage → more focus on features.
🚀 Ready to approve & ship.
PAO (DevRel)
🔍 CI/CD Contributor Guide ReviewReviewed by: Booster (CI/CD Engineer) on behalf of Dina Berry ✅ Strengths1. CI Requirements Clarity: GOOD
2. CI Hardening in Scope
These are solid infrastructure improvements that support contributor success indirectly.
|
| Section | Current Status | Recommendation |
|---|---|---|
| Issue templates (2a) | ✅ Planned but incomplete | Add ci_bug.yml template for CI-specific failures |
| FAQ: CI failures (2e) | ✅ Mentioned but vague | Expand to "How to Debug CI Failures" subsection with concrete commands |
| FAQ: Branch strategy (2e) | ✅ Strong | Keep as-is (dev vs main is critical) |
| Changeset requirement (2e) | ✅ Covered | ✓ Good |
| FAQ: What's .squad/? (2e) | ✅ Strong | ✓ Good |
| CI/CD documentation in README (2f) | Link to CI section in CONTRIBUTING.md |
📋 Actionable Next Steps
Before shipping this PR:
-
If Issue Templates Ship in This PR:
- Confirm all 4 templates (bug, feature, docs, config) have been implemented
- Add a 5th:
ci_bug.ymlfor CI-specific failures - Add auto-labels per template (add
type:cifor CI template)
-
If FAQ Expands in Follow-up:
- Create a dedicated "Debugging CI" subsection
- Include:
npm run lint,npm test,npm run buildcommands contributors can run locally - Link to GitHub Actions output interpretation guide
-
.squad/Explainer (P1 — Critical):- ✅ This is the right priority. Prevents PR friction immediately.
🎓 Bottom Line for External Contributors
After this PR ships (with CI template addition), external contributors will be able to:
- ✅ Understand why CI checks exist
- ✅ Know what branches to target (dev, never main)
- ✅ Know changesets are required
⚠️ Partially understand how to debug CI failures (needs FAQ expansion)- ✅ Report CI bugs in a structured way (needs ci_bug.yml template)
Recommendation: Approve with a note to add the CI issue template and FAQ subsection.
@bradygaster — Is the CI template (5th template type) in scope for this PR, or should it be a follow-up? If follow-up, I'd recommend making it immediate (P1.5) since external contributors hit CI issues regularly.
FIDO Quality Review: Contributor Guide Improvements Proposal ✅Status: APPROVED — This proposal is well-scoped, data-driven, and will measurably reduce contributor friction. Strengths✅ Data-Driven — 4/100 external PRs analyzed; real friction patterns identified (PR #639: wasted effort on deprecated feature; PR #633: wrong branch/empty body) Will This Reduce Friction? Yes, measurably.
4 HIGH-confidence friction fixes = strong ROI. Clarifications Needed
RecommendationShip the proposal. The plan is solid, gaps are real, ROI is clear. Once implemented, expect measurable increases in external PR quality and frequency. After merging, prioritize 2a+2c+2e (4 hrs) next sprint for highest immediate impact. FIDO Sign-Off: ✅ Approved. |
🤖 Automation Analysis: Contributor Guide Improvements (PR #702)Brady wants maximum automation — here's what can be automated, partially automated, or should remain manual for each ✅ FULLY AUTOMATABLE ITEMS1. Issue Templates (2a) → Auto-Labeling + Template ValidationWhat it does:
How to implement:
Extends existing:
Effort: 2–3 hours (YAML templates + workflow) Code: Would look like:
2. Good First Issue Auto-Detection (2b) → Workflow + Curation ToolWhat it does:
How to implement:
Extends existing:
Effort: 4–6 hours (script + workflow + testing) Sample workflow trigger: 3. .squad/ Protection → CI Gate (Blocking PR merge)What it does:
How to implement:
Extends existing:
Effort: 1–2 hours (script + workflow) Code sample:
\\ 4. Contributor Onboarding → Welcome BotWhat it does:
**How to implement:**�
Extends existing:
Effort: 1–2 hours (action + workflow) 5. FAQ Auto-Linking → Bot in Issues/PRsWhat it does:
How to implement:
Extends existing:
Effort: 2–3 hours (keyword list + regex matching + response templates) 6. PR Quality Gate → Automated Checklist ValidationWhat it does:
How to implement:
Note: PR_REQUIREMENTS.md already defines these; CI can enforce programmatically Extends existing:
Effort: 2–3 hours (validation script + workflow)
|
| Rank | Item | Automation Type | Effort | Payoff | Dependencies |
|---|---|---|---|---|---|
| 1 | .squad/ Protection (3) | Blocking CI gate | 1–2h | HIGH | None |
| 2 | PR Quality Gate (6) | Blocking checklist | 2–3h | HIGH | None |
| 3 | Issue Template Auto-Labeling (1) | Workflow + script | 2–3h | MEDIUM | Issue templates must exist |
| 4 | Welcome Bot (4) | Workflow | 1–2h | MEDIUM | None |
| 5 | Good First Issue Detection (2) | Workflow + script | 4–6h | MEDIUM | Requires curation tool |
| 6 | FAQ Auto-Linker (5) | Keyword-based workflow | 2–3h | MEDIUM | FAQ must exist in docs |
| 7 | Stale Issue Mgmt (8) | Configured action | 1h | LOW | None |
| 8 | Conduct Monitor (7) | Keyword workflow | 3–4h | LOW | Too many false positives |
📋 QUICK REFERENCE: What to Ship in This PR
This PR is documentation-only (proposal + workflow hardening). For maximum automation, follow up with:
PR #2 (Immediate):
- Issue templates (YAML files in .github/ISSUE_TEMPLATE/)
- Workflow: \squad-protect-internal.yml\ (block .squad/ changes)
PR #3 (Week 1):
- Workflow: \squad-pr-quality-gate.yml\ (PR checklist validation)
- Workflow: \squad-welcome.yml\ (first-time contributor welcome)
PR #4 (Week 2):
- Workflow: \squad-good-first-issues.yml\ (auto-detect candidates)
- Workflow: \squad-faq-responder.yml\ (keyword-based FAQ linking)
Supporting docs (in this PR or next):
- FAQ section in CONTRIBUTING.md
- .squad/ explainer in CONTRIBUTING.md
- README contributing enhancement
💡 Key Insight for Brady
Automation payoff: With workflows 1–6 implemented, Squad could reject ~70% of invalid PRs before human review, a
auto-welcome first-timers, and auto-flag good opportunities for contributors. That's fewer back-and-forth comments, l
less context-switching for Tamir/Brady, and better contributor experience.
Cost: ~12–15 hours of workflow development. Breaks even after ~20 external contributor interactions (rough estim
mate based on current friction patterns).
This analysis assumes existing workflows (\squad-triage.yml, \squad-heartbeat.yml) can be extended. If Squad's CI/CD
infrastructure has constraints, let me know and I can adjust.
___BEGIN___COMMAND_DONE_MARKER___0
PS C:\Users\diberry\project-dina>
|
🔄 Ralph PR status
Proposal for contributor guide improvements. Draft + merge conflicts. Needs conflict resolution if this moves forward. |
Audited all contributor-facing files on dev branch and identified 8 gaps in external contributor experience. Proposes 7 deliverables prioritized by maintainer time savings: P1: Issue templates, good-first-issue curation, .squad/ explainer P2: CODE_OF_CONDUCT.md, contributor FAQ, README contributing section P3: SECURITY.md typo fix Goal: contributors self-serve from docs instead of asking Brady/Tamir the same questions repeatedly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diberry
force-pushed
the
squad/contributor-guide-proposal
branch
from
ae1bceb to
99c17cb
Compare
|
🤖 Upstream Maintenance Check
|
There was a problem hiding this comment.
Pull request overview
Adds a new proposal document describing gaps and a prioritized plan to improve contributor-facing documentation and GitHub project hygiene, aimed at reducing maintainer back-and-forth and improving external contribution success.
Changes:
- Introduces
docs/proposals/contributor-guide-improvements.mdwith an audit of current contributor docs and identified friction patterns. - Proposes prioritized deliverables (issue templates,
.squad/explainer, FAQ, README enhancements, CoC, SECURITY typo fix) and success criteria.
| > **Author:** Flight (Lead) | ||
| > **Date:** 2025-07-24 | ||
| > **Status:** Draft — awaiting team review | ||
| > **Goal:** External contributors can be successful with issues and PRs without requiring repeated guidance from Brady and Tamir. | ||
|
|
There was a problem hiding this comment.
The proposal header metadata format is inconsistent with the other existing docs/proposals/*.md files (which use plain **Issue:**/**Author:**/**Date:**/**Status:** lines, not a blockquote). For consistency and easier scanning, consider matching the established proposal header format and adding an **Issue:** field (or N/A).
| > **Author:** Flight (Lead) | |
| > **Date:** 2025-07-24 | |
| > **Status:** Draft — awaiting team review | |
| > **Goal:** External contributors can be successful with issues and PRs without requiring repeated guidance from Brady and Tamir. | |
| **Issue:** N/A | |
| **Author:** Flight (Lead) | |
| **Date:** 2025-07-24 | |
| **Status:** Draft — awaiting team review | |
| **Goal:** External contributors can be successful with issues and PRs without requiring repeated guidance from Brady and Tamir. |
| **Proposed topics:** | ||
| - "My PR CI is failing" — how to read CI output, common causes (missing changeset, build errors, lint failures) | ||
| - "Which branch do I target?" — always `dev`, never `main`. With a bold callout box. | ||
| - "Do I need a changeset?" — yes, always. How `npx changeset add` works. What to pick for patch/minor/major. |
There was a problem hiding this comment.
The proposed FAQ guidance says contributors always need a changeset and references npx changeset add, but the current repo state doesn’t appear to have Changesets wired in (no changeset* scripts in root package.json, no @changesets/cli in package-lock.json, and no workflow checks). As written, this would likely mislead contributors—either adjust the proposal to reflect current enforcement, or call out re-introducing Changesets tooling as a prerequisite for that FAQ guidance.
| - "Do I need a changeset?" — yes, always. How `npx changeset add` works. What to pick for patch/minor/major. | |
| - "Do I need a changeset?" — once Changesets tooling is (re-)enabled, most PRs will need one. Document how `npx changeset add` works and what to pick for patch/minor/major. Until then, follow maintainer guidance (CI does not currently enforce changesets). |
What
Proposal for improving contributor-facing documentation so external contributors can be successful without repeated guidance from maintainers.
Why
Only 4 external PRs in the last 100 (2 closed without merge due to friction). No issue templates, no good-first-issues tagged, no .squad/ explainer, no CODE_OF_CONDUCT, no contributor FAQ. Brady and Tamir answer the same questions repeatedly.
How
Audited all contributor-related files on dev. Reviewed 4 external PRs for friction patterns. Identified 8 gaps. Proposes 7 deliverables in priority order:
Full analysis at docs/proposals/contributor-guide-improvements.md.
Testing
Docs
Exports
N/A
Breaking Changes
None
Waivers
Waived: (c) Code Quality (tests) — documentation-only change, structural exemption per PR_REQUIREMENTS.md