Ask first: should this be open source?¶

Good reasons:

• You want others to use it, learn from it, or improve it
• You want a public portfolio
• You're scratching an itch others probably have
• You want to give back

Things to be honest about:

• Publishing code is not the same as running a project. The moment people use it, you'll get issues, feature requests, and questions. You're allowed to say no, and you're allowed to mark a project as "unmaintained" — but decide your level of commitment up front and say so in the README.
• Check your employment agreement. Some employers claim ownership of code written on their time or equipment, or related to their business.
• Scrub secrets and history. Run gitleaks or trufflehog across the full history, not just HEAD. If anything ever leaked, rotate it — rewriting history doesn't un-leak a credential.

The essential files¶

my-project/
├── README.md            # What it is, why, how to install, how to use
├── LICENSE              # Or LICENSE-MIT + LICENSE-APACHE for dual licensing
├── CONTRIBUTING.md      # How to build, test, and submit changes
├── CODE_OF_CONDUCT.md   # Expected behaviour and how it's enforced
├── SECURITY.md          # How to report vulnerabilities privately
├── CHANGELOG.md         # Human-readable history of changes
├── .gitlab/
│   ├── issue_templates/
│   │   ├── Bug.md
│   │   └── Feature.md
│   └── merge_request_templates/
│       └── Default.md
├── .gitlab-ci.yml
└── src/

README.md¶

The README is your project's front door. Most people decide within 30 seconds whether to keep reading. Include:

1. Name and one-sentence description — what does it do?
2. Why — what problem does it solve, and why use this over the alternatives?
3. Status — experimental, stable, maintained, unmaintained?
4. Install — copy-pasteable commands
5. Quick start — the smallest useful example
6. Configuration / usage — or a link to full docs
7. Contributing — link to CONTRIBUTING.md
8. License

A screenshot or terminal recording (asciinema, vhs) for a CLI tool beats three paragraphs of explanation.

CONTRIBUTING.md¶

• How to set up a development environment
• How to run tests, linters, and formatters
• Branch and commit message conventions (e.g. Conventional Commits)
• Whether you require DCO sign-off
• What kind of changes you'll accept, and what you won't
• Expected response times (honesty here prevents frustration)

CODE_OF_CONDUCT.md¶

The Contributor Covenant is the de facto standard and is used by tens of thousands of projects. Adopting it signals that the project is a welcoming space. Include a real contact address for reports; a code of conduct with no enforcement path is decorative.

SECURITY.md¶

# Security Policy

## Supported versions

Only the latest release receives security fixes.

## Reporting a vulnerability

Please do not open a public issue. Email [email protected], or use
GitLab's confidential issue feature. You can expect an acknowledgement
within 7 days.

CHANGELOG.md¶

Follow Keep a Changelog (Added, Changed, Deprecated, Removed, Fixed, Security sections per release). Generated commit dumps are not a changelog — write for users, not for git log.

Versioning and releases¶

• Use Semantic Versioning: MAJOR.MINOR.PATCH. Bump MAJOR for breaking changes, MINOR for new backwards-compatible features, PATCH for fixes. Before 1.0.0, anything may change.
• Tag releases (git tag -s v1.2.0 for signed tags).
• Publish release notes with each tag.
• Ship to where your users are: crates.io, a container registry, distro packages, prebuilt binaries for major platforms.
• Automate it. Tagging should trigger CI to build, test, package, and publish — releases done by hand at 11 p.m. are where mistakes happen.

CI and project health¶

At minimum, CI should run on every MR:

• Build
• Tests
• Linters and formatters (cargo fmt --check, cargo clippy -- -D warnings)
• Dependency and license audit (cargo deny check, cargo audit)
• Secret scanning

Going further on supply-chain hygiene:

• OpenSSF Scorecard — automated grading of security practices
• OpenSSF Best Practices Badge — a self-certification checklist that's genuinely useful as a to-do list
• SBOMs — generate a Software Bill of Materials (CycloneDX or SPDX) with each release
• Signed artifacts — Sigstore / cosign for containers and binaries
• REUSE — the FSFE's spec for machine-readable copyright and licensing on every file
• Dependabot / Renovate — automated dependency update MRs

Choosing where to host¶

A common pattern is to develop on the platform you prefer and push-mirror to GitHub for discoverability, with a note in the README pointing to where issues and MRs should go.

Launching¶

• Write a short post explaining what you built and why.
• Share it where the relevant people are: subreddits, Hacker News ("Show HN"), Lobsters, Mastodon, language-specific forums (users.rust-lang.org, This Week in Rust's call for participation).
• Add topics/tags to the repository so it shows up in searches.
• Label a few genuinely easy issues good first issue — and keep them easy. That's how you get your first contributors.

Most projects don't take off immediately, and many never get a large community. That's fine. A useful tool with five users is a success.