Skip to content
Open {re}Source

    05Creating

    Planning Your Project

    Most open-source projects are planned in a README and a TODO.md. That’s fine. Five short pieces of writing save you pain later: the problem, what the project won’t do, the milestones, who decides, and how you’ll say no.

    Write the problem down before the code#

    Two paragraphs in the README: what’s broken today, and for whom. If you can’t write them, the project isn’t ready, however far along the code is.

    Then answer the question every visitor asks: why would I use this over X? Name X, and look for it on npm, PyPI, crates.io or GitHub first: if it already solves the problem, a pull request there may beat a new repo. If yours does something X doesn’t, that sentence is your pitch.

    Last, decide whether you want contributors or only users. Open source doesn’t oblige you to accept code: SQLite is open source but not open contribution. Either is fine. Say which in the README: it decides how much of your time goes to reviews.

    When: before you make the repo public.

    Say what the project won’t do#

    Scope in open source isn’t a feature list: features arrive as issues and pull requests whether you planned them or not. What protects a project is the list of what it won’t do, written where contributors read it.

    Three examples of the pattern:

    • esbuild’s roadmap lists what won’t go in the core: TypeScript type checking, hot-module reloading, module federation, and more. Each request for them gets a link, not a debate.
    • Prettier’s option philosophy explains why it no longer accepts new formatting options.
    • Vite’s philosophy page keeps the core lean and sends the rest to plugins.

    A “Non-goals” section in your README does the same job in five lines. It’s easier to write it before the first feature request than to explain it in the comments of one.

    When: as soon as someone other than you opens an issue.

    Plan with milestones, not dates#

    A volunteer project that promises dates breaks the promise. Milestones say what, not when:

    • v0.1: I use it myself.
    • v0.x: other people use it, and things may still break. SemVer says a 0.y.z version is for initial development: anything may change at any time.
    • v1.0: I’d be embarrassed to break it. From here, a breaking change means a new major version.

    On GitHub, a milestone groups the issues and pull requests of a version and shows how many are closed: the whole roadmap most projects need. A ROADMAP.md becomes useful when people ask “is X planned?” often enough.

    When: at the first release anyone else installs.

    Governance: you, until it isn’t#

    A one-person project doesn’t need a steering committee. It needs one honest line in the README or the contributing guide:

    Decisions are made by @you. This will change when there are more of us.

    That line answers who has the last word, and it promises nothing you can’t keep. Write a real governance document when a second person has merge rights, not before: the rules depend on who they are.

    When: the day you give someone else write access.

    Decide how you’ll say no#

    Sustainability, for a new project, isn’t money: it’s keeping the project something you still want to work on. The first threat is the pull request you don’t want to merge and don’t know how to refuse.

    Decide in advance:

    • what you’ll close without discussion (anything in the non-goals),
    • how much time a week the project gets from you, and write it in the README if people wait on you,
    • where conversations happen: GitHub Discussions, a chat, or issues only. Pick one, link it from the README, and answer each question in one app, not three.

    Money comes later, if at all. The Financing module covers it for when the project has users who depend on it.

    When: before the first issue you’d rather not answer.

    Do this now#

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

    Go further#