Skip to content
Velloreth
Projects 5 min read

Building an Open Source Project: Beyond the Code

First-person guide to open source beyond the repository: licenses, README, governance, security policy, maintainer burnout, and sustainability.

By

Writing the code is the easiest part of an open source project. Everything that comes after — the license, the README, the issue templates, the security policy, the decision of what not to accept — determines whether the project survives its first contributor.

I have open sourced a few small libraries and one project that other people actually use. This is what I learned about the parts that are not writing code.

The license comes first

Pick a license before the first public commit. Without one, the default is “all rights reserved,” which means nobody can legally use, copy, or modify your code even if it is on GitHub. A repository with no license is not open source; it is just public code.

I default to MIT for small libraries: short, permissive, and understood. It lets anyone use the code commercially with almost no restriction, and companies do not fear legal review. If I wanted derivative works to remain open, I would look at AGPL. If I wanted patent protection alongside copyright, Apache 2.0. The choice depends on what you want to encourage, not on which license is trendy.

Do not write your own license. Do not use the “Unlicense” unless you understand that it disclaims copyright entirely, which some jurisdictions do not recognize. Pick a standard license, include the full text in a LICENSE file at the repository root, and add a one-line copyright header to source files if you want to be explicit.

README is the product

Most people who visit your repository will never file an issue. They will read the README and decide in thirty seconds whether to use it or leave. The README is documentation, marketing, and the contribution invitation all at once.

Mine includes:

  • What the project does, in one sentence
  • An installation command (npm install or pip install or go get)
  • A minimal usage example, copy-pasteable
  • What it does not do, stated plainly
  • How to report a bug and how to contribute

I also state the support level explicitly: “Maintained in my spare time; bugs fixed as I can, no guaranteed response time.” That one sentence sets expectations and saves me from apologizing later.

Bad READMEs assume the reader already knows the problem the project solves. Good READMEs start with the problem and show the solution in code.

Contribution infrastructure

Before accepting a pull request, add:

  • CONTRIBUTING.md — how to build, test, and submit changes
  • CODE_OF_CONDUCT.md — how people are expected to behave
  • Issue templates — bug reports and feature requests with structured fields
  • Pull request template — what a good PR includes

These look like bureaucracy until someone submits a five-line change that breaks the build and does not include tests. Then they are a filter that protects your time.

I require tests on every PR that changes behavior. I also require that the commit messages explain why, not just what. These rules are lightweight but they keep the project maintainable by one person.

Do not gate contributions behind a contributor license agreement (CLA) unless you have a specific legal reason. CLAs discourage casual contributors for little benefit on small projects.

Maintenance is a schedule, not a mood

The first popular issue feels like validation. The tenth issue feels like obligation. The fiftieth feels like a second job you did not apply for.

I learned to set boundaries early:

  • Issues get a first response within a week, not within a day.
  • I review pull requests on Sundays, not on weeknights.
  • Features I do not personally need get declined unless someone offers to maintain them.
  • Dependabot updates are batched and applied monthly, not continuously.

Burnout in open source usually comes from saying yes to everything and never saying no to anything. Saying “this is out of scope” is a kindness to your future self.

It is okay to archive a project. It is okay to say “I am no longer maintaining this.” A maintained project with one active user is better than an abandoned project with ten thousand.

Security and vulnerability reports

Publish a SECURITY.md before someone finds a vulnerability. It should say:

  • How to report privately (email or a private advisory)
  • How quickly you will respond (realistically)
  • That you will not ask for public disclosure before a fix is available

When a report arrives, acknowledge it fast even if the fix takes weeks. A reporter who hears nothing assumes you are ignoring them and posts publicly. A reporter who hears “we received this and are working on it” usually waits.

Do not offer bounties unless you can pay them. A promise of recognition is honest; a promise of money you cannot deliver is not.

Governance as the project grows

If more than one person maintains the project, write down how decisions are made. Who approves releases? Who can merge pull requests? What happens when maintainers disagree?

For a solo project, governance is you deciding what goes in. Be transparent about that: “I maintain this alone; final calls are mine.” Contributors know where they stand, and you do not pretend to a community process you do not run.

Sustainability means time, not just money

Sponsorship buttons and Open Collective pages are nice, but most small open source projects make essentially nothing from them. Sustainability is primarily about whether the maintainer still has time and energy.

If your project becomes infrastructure that companies depend on, ask those companies for support — money, employee time, or both. Do not wait until you are burned out to ask. And if no one pays, scale the project back to what you can afford to maintain, rather than collapsing under it.

Open source is sustainable when the maintainer can still enjoy it. Everything else is a negotiation with that limit.

Frequently asked questions

Which license should I choose?
MIT and Apache 2.0 are permissive and let others use the code commercially with minimal restrictions. GPL-family licenses require derivative works to stay open. Choose based on whether you want maximum adoption or maximum reciprocity, and do not ship without one.
Do I need a CODE_OF_CONDUCT?
If you want anyone besides yourself to contribute, yes. It sets the baseline for behavior and gives you a basis to remove people who violate it. Without one, you are improvising moderation during a conflict.
How do I handle security vulnerabilities?
Publish a SECURITY.md with a private reporting address (email or advisories), state how quickly you will respond, and never ask a reporter to disclose publicly before you have had a chance to fix it.
Can open source be sustainable without funding?
Yes for small tools maintained as a hobby, but not for infrastructure that people depend on daily. Sustainability means time, not just money; if the project matters to others, someone has to be paid or the maintainer will burn out.