Guide

Every Checklist in the Guide

Every chapter ends with a “Do this now” checklist. Here they all are, by module, each linking back to its chapter. A box you tick here is ticked in the chapter too, in this browser, and “Copy as Markdown” turns a list into a task list for an issue.

Getting Started#

Source Code Hosting Platforms: GitHub and the Alternatives #

Check where the three projects you use most really live: the GitHub repository can be a mirror, and its README says so.
If one of them lives on its own GitLab or on Codeberg, create an account there before you need it.
If you maintain a project, add a second push URL to its remote, so every push leaves a copy somewhere else.

Finding Open-Source Software to Use #

Search the registry, package manager or store you install from before a web search.
Read the license identifier and check it allows what you’ll do: run it, or ship it inside your code.
Check the latest release date and the known advisories on the registry or on deps.dev.
Open the Scorecard and read the checks at 0 that matter for how you’ll use the project.
Look at the history of the LICENSE file for a license change.
Give the repository five minutes with Reading a Repository in Five Minutes.

Reading a Repository in Five Minutes #

Open Source Etiquette: Talking to Strangers Who Owe You Nothing #

Open the CONTRIBUTING.md of a project you use, and find how it wants questions and ideas: issues, Discussions or a chat.
Find its CODE_OF_CONDUCT.md, and the contact it gives for reports.
Next time you’re about to comment “+1”, react with 👍 and click Subscribe instead.
Before you post your next comment, read it once as the maintainer, on a Sunday evening.
Say thanks on one issue that got fixed for you.

Git and GitHub Basics You Actually Need #

Set user.name and user.email with your GitHub no-reply address, then check them with git config --global --list.
Turn on two-factor authentication on GitHub, if it isn’t on yet.
Install the GitHub CLI and run gh auth login.
Fork and clone a project you use with gh repo fork <owner>/<repo> --clone, and check that git remote -v lists origin and upstream.
Make a branch from upstream/main, change two lines, and stage only one with git add -p.

Contributing#

Finding a Project to Contribute To #

List the dependencies, tools and editor extensions you use every day, and open their issue trackers.
Open /contribute on two of them.
Bookmark an issue search for your language, with no:assignee and a recent created: date.
Pick three candidate issues and give each repository the five-minute check.
Read the contributing guide of the one you pick, and start the way it asks: a comment, an assignment, a proposal or a pull request.

Your First Contribution, Step by Step #

Find the CONTRIBUTING.md of the project you want to contribute to, and read the section on pull requests.
Check which Node.js (or Python, or Go) version its CI uses, often in .nvmrc or the workflow files, and install that one.
Clone it and run the command its README gives you, before you change anything.
Before you push, run the checks CI will run: the workflows in .github/workflows/ list them.
Open your pull request from a fork on your personal account, with “Allow edits by maintainers” ticked.
Put a reminder in your calendar two weeks after you open it.

How to Write a Bug Report That Gets Fixed #

Search open and closed issues for the error message, in quotes.
Reproduce the bug on the latest release.
Build a reproduction from the project’s starter, and reduce it until removing anything makes the bug disappear.
Write expected and actual, and the last version that worked if you know it.
Add the versions of the project and of what runs it.
Check the title names the symptom, then post, and look at the issue again in two days.

Non-Code Contributions Maintainers Actually Want #

Next time a docs page confuses you, fix the sentence before you close the tab.
Open the issues of a project you use, sorted by newest, and try to reproduce one report.
Tab through that project’s docs site with the keyboard only.
Answer one unanswered question in its Discussions or chat.
Check whether it has a Sponsor button, and whether your company uses it.

Creating#

Planning Your Project #

Write the problem in two paragraphs at the top of the README, with the “why this over X” sentence.
Search the package registries for X before writing more code.
Add a “Non-goals” section to the README, even with two lines.
Create a v0.1 milestone on GitHub and put the issues that block it in it.
Add the “Decisions are made by…” line to the README or the contributing guide.

The Files That Turn a Repository Into a Project #

Open /(owner)/(repo)/community on your repository, and list what’s missing.
Read your README’s first screen as a stranger: does it say what the project does and show it?
Search your code of conduct for a placeholder, and put a real address in it.
Clone your repository into a new folder and follow CONTRIBUTING.md to the letter. Fix the first step that fails.
Add a SECURITY.md that points to private vulnerability reporting.
Add one issue form, for bugs, with three required fields.

Community From Day One #

Add a code of conduct that names at least one contact.
Set up Discussions, edit the welcome post to three lines, and pin it.
Write two good first issues, each with the file to change and what “done” looks like.
Say in the README where to ask questions and how to reach you.
Decide now that you’ll answer the first pull request within a day.

Licensing & Legal#

Choosing a License: Four Questions and a Table #

Check that your project has a LICENSE file, and that GitHub shows its name in the About box.
Put the SPDX identifier in the license field of your manifest.
If you use a GPL-family license, decide between “only” and “or later”, and use the matching identifier.
Look up the license of your three biggest dependencies, and check that it allows what you do with them.

License Compatibility: What You Can Combine, and the Tools That Check #

Run a license checker on your production dependencies.
Read every line that isn’t MIT, ISC, BSD or Apache-2.0, and write down why it’s fine, or replace the package.
Add an allow list to CI, so a new license shows up in a pull request.
List the non-code files in your repository (fonts, images, docs) and the license of each.

Relicensing: The Source-Available Wave, and the Forks That Answered #

List the databases, search engines and infrastructure tools you run, and check the license of the exact version you deploy.
For each one under the BSL, read its Additional Use Grant, and write down why your use is allowed.
Before a big contribution to a company-owned project, read its CLA and check whether it lets the company relicense your code.
If you’re starting a company around your project, pick its license now, the way you’d pick it if the project got popular.

CLA or DCO: What You Sign When You Contribute #

Set git config --global user.email to the address you want in public sign-offs, and check that GitHub links it to your account.
Before your next contribution to a company-owned project, read its CLA and answer the three questions above.
If you contribute at work, find out whether your employer has signed a corporate CLA with the projects you contribute to.
If you maintain a project, write down in CONTRIBUTING.md what contributors agree to: inbound=outbound, a DCO sign-off, or a CLA, and why.

Licenses for Things That Aren't Code: Docs, Fonts, Hardware, Data and Models #

List what your repository contains besides code (docs, images, fonts, data, designs), and write down the license of each.
Put code samples in your documentation under a code license (CC0 or your project’s license), and say so.
Before using a CC-licensed image or text in anything commercial, check that its license has no NC.
Before building on a model, read its license for a user threshold or a list of prohibited uses.

Trademarks, Names and Logos: What Your License Doesn't Cover #

Search your project’s name in the USPTO and EUIPO databases, and in your package registry, before you grow attached to it.
Add a “Trademark” section to your README, or a TRADEMARK.md: who holds the name, what’s allowed without asking, whom to ask for the rest.
Say which license covers your logo, and that it doesn’t cover the trademark.
If a company sells around your project, register the name or ask your foundation to.

Maintaining#

What a Maintainer Actually Does #

Count your last week: run repo:<owner>/<repo> is:pr created:<Monday>..<Sunday> in GitHub’s search, then the same with is:issue and is:merged.
Log your hours for one week, by kind: review, triage, dependencies, code, support.
List the pull requests nobody has answered: repo:<owner>/<repo> is:pr is:open review:none comments:0.
Name your mode, solo, core team or community, and say it in your README.

Saying No: Five Replies That Keep Contributors Coming Back #

Write a “Non-goals” section in your README, even three lines, and link it from CONTRIBUTING.md.
Save the five replies above in your GitHub settings, reworded in your own voice.
Find the oldest open issue you know you won’t do, and close it as not planned, with the reason.
Label help wanted the issues you’d merge but won’t write yourself.

Reviewing Pull Requests: What to Check, What to Say, When to Close #

It fixes the issue, all of it and only it.
A bug fix comes with a test that fails without the fix.
Docs, examples and the changelog follow the change in behavior.
No breaking change hides in it: public API, options, defaults, output format.
Anything visible works with a keyboard and a screen reader, and new strings can be translated.
It’s small enough to review in one sitting.
CI is green, on the checks that matter for this change.

Reviewing Pull Requests: What to Check, What to Say, When to Close #

Add a CODEOWNERS file to your project, even with one line.
Save the three closing replies above in your GitHub settings.
Close the oldest open pull request you know you won’t merge, with the reason.
In your next review, label every comment, and add one praise:.

Running a Community Without It Running You #

Write in the README where to ask questions and where to chat, and how long an answer usually takes.
Turn on Discussions, or pick a forum, and add it to contact_links in the issue template config.
Label three issues as good first issue, each with the file to change and what “done” looks like.
Name the authors in your next release notes, with an @mention, and keep the New Contributors section.
Pick one cadence you can keep, and put the next date in your calendar.
Check that your code of conduct names more than one person to contact, and that they know it.

Governance: Who Decides, and How to Write It Down #

Write down who decides in your project today, in a GOVERNANCE.md, even one paragraph.
List the maintainers in the repository, with what each one can do.
Decide what needs more than a pull request, and write how those decisions are made.
Add an emeritus section, and thank the people who stepped back.

Security for Maintainers: Before, During and After the First Report #

Add a SECURITY.md with supported versions, how to report and your response time.
Turn on private vulnerability reporting.
Require two-factor authentication for everyone with write access.
Replace long-lived publish tokens with trusted publishing.
Set permissions: contents: read at the top of every workflow.
Pin third-party actions to full commit SHAs, and let Dependabot update them.
Turn on secret scanning and push protection.
Run Scorecard, and fix the first finding that applies to your project.

Burnout, Succession and the End of a Project #

Open Insights > Contributors on your project, over its whole history, and read your share.
Write down what only you can do: publish, the domain, DNS, secrets, social accounts.
Give release rights to a second person you trust: a co-owner on the package registry, or trusted publishing from CI.
Name your successor in your head. Then write it down in the repository, with what they’d need.

Promoting#

Building a Strong Project Identity #

Write your project’s values in three to five lines, where contributors will read them: the README or the contributing guide.
Check your name before you commit to it: the domain, GitHub and GitLab, a web search, a trademark search.
Look at your logo as a favicon and in one color. If it doesn’t survive both, simplify it.
Write a one-page style guide: how to use the logo, the color codes, the fonts.
Open your homepage as a stranger would. The first screen says what the project does, what it solves, and how to contribute.

Financing#

Effective Fundraising Strategies #

List your top 20 dependents: GitHub’s Dependents tab, the ecosyste.ms API, and the companies behind your last 50 issues.
Publish tiers with prices on GitHub Sponsors or Open Collective, and link them from the README, the docs footer and the package metadata.
Write three yearly tiers with an invoice option, and send the email above to the three companies at the top of your list.
Pick one grant whose next deadline is within three months, and write the three answers before opening the form.

Open Source at Work#

License Compliance at Work: The Policy, the Notices and the SBOM #

Generate an SBOM for one product you ship, compare its component count with npm ls --all --omit=dev (or your ecosystem’s equivalent), and count its licenses.
Look up every license on that list you’d never heard of.
Find out who answers “can we use this library?” in your company, and write that name in the policy.
Open the product you ship and find its open-source notices: a settings screen, an about page, a file in the image.
Answer the 34 questions of the OpenChain self-certification checklist, and count the noes.

Vulnerabilities in What You Ship: Triage, Upstream Fixes and the CRA #

Run npm audit, pip-audit, cargo audit or osv-scanner on one product you ship, and look up each advisory in KEV and EPSS.
For each KEV entry in that list, find out whether your product runs the vulnerable code.
Name who sends the 24-hour early warning, and who covers when they’re away.
Send a test report to your security contact address, and time how long the answer takes.
List the private patches you carry on open-source components, and send one of them upstream.

Open Source & AI#

AI-Assisted Contributions: A Policy You Can Copy #

Add an “AI tools” section to your CONTRIBUTING.md: the policy above, or your own in three lines.
Add the “AI tools” checkboxes to your pull request template.
Add to your SECURITY.md that a report needs a reproduction and must disclose AI use.
If outside pull requests outnumber your reviews, set a limit on open pull requests without write access.
Save a reply that asks the author to explain the change in their own words.

Contributing with AI Tools Without Annoying Maintainers #

Before your next contribution, read the project’s AI rules yourself: CONTRIBUTING.md, any AI policy file, the pull request template.
Save the disclosure line above as a snippet, and fill it in whenever a tool wrote part of a change.
Before you push, read your own diff and revert every line the issue didn’t ask for.
Check that your tool doesn’t add Signed-off-by: or other trailers to your commits on its own.
Reproduce any bug a tool found for you before you report it, and say in the report that a tool found it.