This is an automated archive made by the Lemmit Bot.
The original was posted on /r/opensource by /u/switchback-tech on 2023-11-20 16:06:56.
Open-sourcing my last app took waayy longer than I expected. Thankfully, I wrote everything I did down. Hopefully this list will save you some time when it’s time to go public.
TL;DR
🧹 Cleanup the Repo (secrets, large files, commits, code, CI, release, vulnerabilities, dependencies)
✍️ Document (LICENSE, README, CONTRIBUTING, CODE_OF_CONDUCT, docs, issue templates, test)
🪧 Share (direct & indirect)
Part I: Cleanup the repo
1. Remove Sensitive Commits
You’ve probably committed sensitive information that you don’t want others to see (e.g. passwords, API secrets, emails).
d258db5 fix: updated DB pw to: SQL_Kiddie_16
Not sure? Try running these commands from the root of your project, replacing YOUR_SECRET with any sensitive text you’re aware of.
# Search your git history to see where you messed up.
# If either of these give you output, you've got a problem.
git grep 'YOUR_SECRET' $(git rev-list --all)
git log -S "YOUR_SECRET" --oneline --name-only --pretty=format:"%h %s"
The easiest way to fix this is to remove any secrets from your HEAD and create a new repo. The downside of this approach is that you lose all your commit history, which makes your code harder to understand for newcomers
If you’re willing to do some extra work to preserve your commit history, I recommend using BFG Repo Cleaner, a tool that removes sensitive files and blobs. I wrote my own step-by-step tutorial for BFG here.
2. Remove large files from git
If you accidentally committed large files like build artifacts, you’re gonna discourage potential contributors by making it slower to clone, push, and pull your repository.You can use BFG or git-filter-branch to remove those large files from your history.
# removing large files from git history using BFG:
java -jar bfg.jar --strip-blobs-bigger-than 100M some-big-repo.git
3. Prevent secrets and large files
Setup precommit hooks and secrets to prevent yourself and others from messing up. Here’s an overview using husty and git-secrets.
4. Reduce commits
When solo hacking on a project, it doesn’t matter whether your commits are semantic, modular, or appropriate.
When collaborating with other developers, however, the commit history’s readability affects your potential support.
Use git wizardry (rebase, squash, merge) to make it easier to read through the git log.
Assuming you’ve been working on the project alone, consider squashing as many commits as possible and updating the git history on origin with git push --force
Lookup the implications of --force and don’t @ me when it breaks everything.
Checkout this video more more about rebase vs merge.
5. Remove unused code
This includes TODO tests stubs, stale branches, functions that are never called, and unnecessary comments.
These smells helped you get up-to-speed when revisiting a section of the codebase, but they’ll slow everyone else down and make them trust your source code less.
That half-implemented code might be useful eventually, though, so remove it in a separate commit and save a link to that commit so you can reference it in the future. (Be careful not to squash that commit in the future step)
6. Fix CI
If you have broken tests, try to fix them. If that’s too much work, remove them and make an issue to fix them. Add a badge to the README that shows the status of the CI tests on main.
7. Create an official release
If your project uses releases (e.g. libraries or mobile apps), create a new version.
8. Fix security vulnerabilities
Releasing your code increases your attack surface, so patch any vulnerabilities, starting with those listed in GitHub’s Security alerts tab.Mention in the README how to you’d like contributors to disclose any vulnerabilities they find. Make it easy for them to contact you directly (rather than opening a public issue).
9. Update dependenciesGet ahead of the inevitable dependency updates by enabling GitHub dependabot, which will autogenerate and tests dependency update PRs.
Part II: Document
10. Add a LICENSE
Choose a license. I prefer MIT, because it’s short and clear.Add the license to your repo.
11. Update README.md
The quality of this file affects how well you convert users and contributors, so don’t cut corners here.
Include proper markdown formatting, reasonable titles, links, badges, and a table of contents.
Set your project apart by also adding GIFs and images.
These visuals are important if you don’t have a landing page because they quickly show what problem your project solves and how it works.
While you shouldn’t breeze through this step, don’t go overboard by cramming too much information into this file.
The purpose of the README is to explain the problem your project addresses and how it solves it while making it easy for people to dive deeper by linking other resources.
12. Add CONTRIBUTING.MD and CODE_OF_CONDUCT.md
Having these files signals that your project is alive and open for contributions (rather than an outdated portfolio piece).No need to innovate here — find a template and adapt anything you need. See CONTRIBUTING.md examples and this CODE_OF_CONDUCT.md example.
13. Write Docs
The gap between your knowledge about the project and what’s documented determines how likely others will contribute.
If your README is the Instagram-able picture of your favorite dessert, your docs are the detailed recipe.
The docs explain how to install, run, debug, test, build, deploy, and troubleshoot your code.
Unless your project is extremely simple, separate these detailed instructions from the README.Try GitHub’s Wiki Pages feature if you need a lightweight option (free for public repos).
If you’re keen to make reading your docs a great experience, create a dedicated static site for them. Here are some good options: GitHub Pages, Cloudflare Pages, Read The Docs, MKDocs, Docusaurus (what I use at docs.compasscalendar.com)
Don’t forget, with great fanciness comes great complexity: webhooks, another repo, more markdown files, versioning, auto-deploying, SEO — all that stuff.
Worth it? Probs.
Finally, link a public Postman collection in your docs if your project includes an API (some examples).
14. Create issue templates
Issue templates prompt contributors to follow your organization structure by including default tags and fields.
They add a little friction for contributors to open an issue, but they also ensure that: the issues are high quality, you won’t keep re-answering the same questions, issues are handled consistently
GitHub comes with pre-defined templates — start by enabling those and customize as needed.
15. Manual Test
The code is clean, the docs are written. It’s time to follow your recipe and eat it before telling others how great it is.From a clean environment, clone/fork the code and do everything your docs explain. Fix or document every hiccup.
Part III: Share
It passes the taste test. Time to let the internet know.For us developers, this is often the hardest part. We think promoting our work is unnecessary, scary, lame. Only those cringey marketing people do that stuff.
"Won’t it grow organically?"Probably not.
Best case scenario: someone stumbles upon your GitHub project after they look you up, find your pinned repo, skim the README, realize they happen to be the target user, install your code, try it, love it, share it for you on X and Reddit.
Most likely scenario: A few people stumble upon it, but no one actually tries or shares it. You lose motivation until the project fades into irrelevance.
Think of sharing your project as a win-win: your target user learns about a viable solution to their problem and you get feedback.
This feedback and attention helps your product and career, as I explain in my YouTube video, Why You Should Open-source 95% of Your Code
16. Share directly
Now that my pep talk is over, here’s how to share your project.Text/email/DM people whose feedback is relevant to the project: Peers who would be the target user, Mods of a subreddit you’d like to post on, People who have launched stuff and have the guts to point out where you’re wrong
If you can get them on a call, do that so you can gauge their reaction to the pitch.
If not, include …
Content cut off. Read original on https://old.reddit.com/r/opensource/comments/17zqk3u/do_these_17_things_before_opensourcing_your/
You must log in or register to comment.