opensource-contributions

Open Source Contributions

The Golden Rule

Make it easy for maintainers to absorb your contribution. Maintainers are often under-resourced volunteers or small teams. Every friction point you remove — unclear reproduction steps, missing tests, bad commit messages, force-pushed history — is time they don't have to spend figuring out what you did and why. The whole point is to help them, not create more work.

When to Use This Skill

• Filing a bug report or feature request on a public repository
• Preparing a pull request for any open source project
• Working on a project without documented contributing guidelines (default posture)
• Reviewing your own PR before submission
• Setting up open source conventions for your own project

Load the relevant phase reference for detailed instructions.

---

Quick Phase Overview

Phase	What It Covers	Reference
0a — Maintainer Conventions	README discipline, LICENSE, CONTRIBUTING.md, issue/PR templates, commit conventions, DCO, release workflow hygiene	references/phase-0a-maintainer-conventions.md
0 — Before You Start	Reading CONTRIBUTING.md, checking existing issues/PRs, triaging bugfix candidates, large-change discussion etiquette	references/phase-0-before-you-start.md
1 — Filing Issues	Bug report and feature request templates, agent disclosure, maintainer workflow ("issue first"), coordinated multi-issue roadmaps, multi-PR plan execution	references/phase-1-filing-issues.md
2 — Pull Requests	Branching conventions, scope assessment, studying existing implementations, cross-repo comparison, commit messages, PR templates, documentation audits, CI setup	references/phase-2-pull-requests.md
3 — After Submitting	CI monitoring, responding to review feedback, what to do if your PR goes stale or gets closed	references/phase-3-after-submitting.md
3.5 — Follow-up After Scope Feedback	Systematic call-site audits, filing comprehensive issues, complementary PRs when maintainer scope notes identify gaps	references/phase-35-followup.md
4 — Release Process	Version bumping, tagging, GitHub Releases vs tags, release workflow anatomy, handling failed releases	references/phase-4-release-process.md

Default Posture (No CONTRIBUTING.md)

When a project has no contributing guide, load references/default-posture.md for defensible defaults on issue filing, PRs, communication norms, and code of conduct.

Agent-Specific Checklist

If you are an AI agent filing or contributing on behalf of a human, load references/agent-checklist.md before submitting anything.

Pitfalls

Load references/pitfalls.md when you're about to submit an issue or PR, or when something goes wrong. Covers: backtick expansion, silent label failures, force-push etiquette, the "I'll just fix it quickly" trap, cross-fork PR issues, post-merge scope creep, the installed-code trap, CI debugging, and more.

---

The Agent-Specific Rule

When filing an issue on behalf of a human, always disclose the agentic nature. Add this line at the bottom of the issue body:

Filed by {{AGENT_NAME}} (AI agent on behalf of {{HUMAN_NAME}})

This is a transparency requirement, not a courtesy. Maintainers deserve to know who they're talking to.

---

Quick Reference Card

Step	Action	Command / Check
0	Read contributing guide	cat CONTRIBUTING.md or .github/CONTRIBUTING.md
0	Check existing issues	gh issue list --search "topic" --state all
1	File a bug/feature	Use template if provided; include reproduction for bugs
2	Issue first before coding	File issue, wait for maintainer feedback, then branch
3	Branch	git checkout -b fix/description
4	Commit	git commit -s -m "fix: description"
5	Run tests locally	make test or npm test or pytest
6	Push	git push -u origin HEAD
7	Open PR	Fill out PR template completely. Use --body-file for complex bodies
8	Monitor CI	gh pr checks --watch
9	Address review	Respond to comments, push fixup commits. No force-push after review
10	After merge	git checkout main && git pull && git tag vX.Y.Z && git push origin main --tags
11	Create Release	gh release create vX.Y.Z --title "vX.Y.Z — Title" --notes-file /tmp/notes.md

---

When NOT to Use This Skill

• You're the sole maintainer of a project with no external contributors and no public collaborators
• You're making a trivial single-line fix to your own code
• The contribution is internal (same organization, same team) with established workflow norms
• You already know the project's contributing guidelines by heart and this is routine
• The issue is a security vulnerability — follow the project's security disclosure policy instead