Skip to content
Open {re}Source

    01Guide

    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#

    • The first page of commits spans weeks or months, not years, and has people on it, not only bots.
    • The repository has a license, a description and a contributing guide.
    • The README says what the project does, how to try it and where to ask, on the first screen.
    • Community standards (/community) shows the files a contributor needs: contributing guide, code of conduct, security policy, templates.
    • Of the five newest issues from outsiders, most got a human answer within a week.
    • The answers are specific and polite, even to vague reports.
    • Sorted by oldest, few open pull requests are more than a year old.
    • Dependency bot pull requests get merged, not piled up.
    • At least two people commit regularly.
    • The latest release, if the project publishes releases, is less than six months old.

    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.

    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#

    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:.

    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, through an npm organization or trusted publishing.
    • 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.