Written by on 2026-10-28

OSS Release: More Than Just Uploading Code

Build . CLI . Gitlab . Projects . Security . Tech . Tooling

Making an internal tool public takes two minutes: set repository to public, add a README, done. The bill comes later — as an issue without reproduction steps, as a pull request against a renamed branch, as an email from a legal department asking whether the license permits commercial use. There’s no good answer if nobody decided beforehand what the project should be.

Seven decisions cost a few hours before launch and define what expectations users and contributors may have. The seventh only joined in the last two years.

1. Honestly Name the Maintenance Status

Repositories implicitly claim to be actively maintained because they say nothing to the contrary. A badge from shields.io clears this up in one line:


!Maintenance

Three levels suffice: actively-developed with ongoing roadmap, passive-maintenance for bugfixes without new features, archived for reference code. Whoever declares passive-maintenance doesn’t need to justify why a PR sits for three weeks. Whoever declares archived saves users a pointless evaluation.

2. The License Is a Product Decision

MIT is the default of many project generators and therefore ends up in repositories where it doesn’t fit the goal. choosealicense.com guides through the selection once the goal is clear:

GoalLicense
Maximum adoption, commercial use desiredMIT, Apache-2.0
Copyleft, derivatives stay openGPL-3.0, AGPL-3.0
Explicit patent protectionApache-2.0
Companies should pay for commercial useDual-Licensing (AGPL + commercial)
No liability, but attribution requiredBSD-3-Clause

For Token-Governance, Apache-2.0 was chosen because the license contains an explicit patent grant from contributors. MIT is silent on patents, and that shows up when a company runs the project through due diligence.

3. Contribution Guidelines as Onboarding

A CONTRIBUTING.md answers what a contributor needs to know before their first commit: How do I report a bug? Does a feature proposal go in a Discussion or an Issue? What does the workflow look like — branch strategy, commit convention, CI? Which issues are labeled good first issue? How does review work, and what tests are expected? Issue and PR templates pre-answer part of this by directly asking for version, reproduction steps, and linked issue.

As a rule of thumb: If the first PR needs more than three rounds of “please format”, “please add tests”, the guidelines are missing. At Token-Governance the CONTRIBUTING.md is three lines long, and every external PR costs two review rounds for formalities. Cleanly decided license, neglected onboarding — the seven points are independent, and each one can be missing.

4. A Release Is More Than a Tag

A tag marks a commit. A release delivers everything for the version switch: changelog, finished artifacts, for breaking changes an upgrade guide and a deprecation policy with concrete advance notice (usual: one major version). The path from tag to publish must be automated, otherwise a step gets left behind at every version. SemVer only governs the number, the changelog you must write yourself. keepachangelog.com explains why generated lists don’t suffice:

“Don’t let your friends dump git logs into changelogs.”

A git log says what was committed. A changelog says what changes for the user. Users rarely update out of curiosity, but because a CVE or a dependency forces them — the shorter the path, the fewer old versions stay in the field.

5. Security Policy with Binding Commitments

A SECURITY.md needs four pieces of information:

  • Reporting channel: a private channel — GitHub’s Private Vulnerability Reporting or a dedicated email address, no public issue
  • Initial response: a concrete commitment, e.g., 72 hours
  • Fix timeline: staggered by severity, e.g., 30 days for Critical with disclosure after 90 days
  • Supported versions: a table showing which minor versions still receive patches

This includes preventive scanning of dependencies: Dependabot or Renovate for updates, Trivy in CI for images and lockfiles. My GitLab Review Bot had this from day one, and no retrofitting was ever needed there. Why CVE scanners alone aren’t enough is in my article on AI Security Updates.

6. Measure Community Health and React

The CHAOSS project of the Linux Foundation defines metrics for project health. Five are actionable even for a solo project: Time to First Response, Time to Merge, number of active contributors (including reviews and triage, not just commits), Bus Factor, and the ratio of stale to open issues.

At my Context Engineering Tools the Bus Factor is 1, no GOVERNANCE.md exists, CODEOWNERS contains one name. The other metrics look good because a single maintainer reacts fast — until they don’t. I personally consider the Bus Factor the hardest number to improve: not through more work, but only by handing out review rights and release keys.

Measuring alone changes nothing: configure stale bot, maintain good first issue, enter active contributors in MAINTAINERS, and from about three maintainers write a GOVERNANCE.md with roles and conflict resolution.

7. Documentation Has a Second Audience

For about two years now, a coding agent often reads the repository before the first human: it generates integration code before anyone evaluates the library. What’s missing from documentation, it invents. For this reader there are dedicated conventions. AGENTS.md describes itself as:

“A simple, open format for guiding coding agents, used by over 60k open-source projects.”

The file sits in the repository root and contains what isn’t derivable from code: build and test commands, project structure, conventions, no-go zones. For project websites there’s llms.txt as a counterpart.

This creates a feedback loop: agents write the documentation that agents read — generated READMEs and AGENTS.md files, produced by one model, consumed by the next. The correction loop is missing. A human following a wrong code example opens an issue; an agent tries a variant and moves on. The antidote is executable documentation: examples that run in CI against the current version.

Agents are also producers. Daniel Stenberg documented for curl what this means for point 5: 415 vulnerability reports, 64 real security issues (January 2024), with growing share of machine-generated false positives.

“Better crap is worse — when reports are made to look better and to appear to have a point, it takes a longer time for us to research and eventually discard it.”

With this volume, 72-hour initial response is hard to keep. Practical: require AI assistance disclosure in SECURITY.md and close reports without reproducible proof of concept immediately. Of the seven points I consider this the most consequential: part of the documentation addresses readers who don’t ask questions and silently propagate errors.

Checklist Before First Announce

  • [ ] README: purpose, installation, quickstart, license, maintenance status, links to guidelines/security/changelog
  • [ ] LICENSE, matching the project goal
  • [ ] CONTRIBUTING.md: workflow, templates, expectations
  • [ ] SECURITY.md: reporting channel, response times, supported versions
  • [ ] CHANGELOG.md from v0.1.0
  • [ ] CI: tests, lint, build, dependency scan on every PR
  • [ ] Release workflow automated: tag → changelog → artifacts → publish
  • [ ] Issue and PR templates
  • [ ] CODEOWNERS
  • [ ] AGENTS.md: build and test commands, conventions, no-go zones
  • [ ] Code examples from README and quickstart run in CI
  • [ ] GOVERNANCE.md from about three maintainers

After Launch

Release is day 1, the rest is operations:

CadenceTasks
WeeklyMerge dependency PRs, triage issues, review PRs within committed time
MonthlyCut release, check metrics, refill good first issue, verify AGENTS.md against changed commands
QuarterlyCommunicate roadmap, recognize contributors in release notes, review archival

The archival question is the most uncomfortable part of this cadence. Setting a project to archived in time is more honest than keeping it half-alive for two years.

Conclusion

The effort isn’t worth it for every repository. A 200-line script without users doesn’t need a GOVERNANCE.md; there license, README, and an honest maintenance badge suffice. The list scales with ambition. For point 7 this applies with a caveat: AGENTS.md and llms.txt are conventions, not standards, and an outdated AGENTS.md harms more than none, because it’s read and believed.

No guarantees either. Complete guidelines and clean releases don’t attract contributors — they only prevent the people who come anyway from failing at formalities. The difference shows in operations: a public repository without these decisions produces issues without context, unmergeable PRs, and users who leave without feedback. A project that made them survives its creator’s departure.

Which of your repositories is public but not released? Write it in the comments.

Links & Resources

Leave a Reply