
Mission 1 of 6
Pick an open source project people will actually star.
Most repos get three stars because they were picked for the wrong reasons. Learn the three tests a project has to pass, then choose one and create its repo with a licence.
What you'll do
Study this week's trending page and spot the three things the individual-made repos share.
Find real ideas, check the competition with two commands, and score each idea on three tests.
Pick a licence on purpose, write a one-line description, and create the public repo with one command.
- A chosen project with a description that passes the ten second test
- A licence decision made with your money options in view
- A GitHub account and the
ghCLI installed and logged in (gh auth login). If not, install anything from GitHub covers it - A terminal you're comfortable in. Terminal survival kit if you're not
- About 50 minutes. Do the searches for real; reading them doesn't count
Your progress0/5
What gets starred, and what doesn't
Understand the three things every starred repo has, so you stop building the kind that gets ignored.
Before you choose what to build, you need to know what makes people star a repo. This step shows you, so you can judge every idea you collect against it.
What a star means
A star is a bookmark. Someone saw your repo, understood in a few seconds what it does, and decided they might want it later. That's the whole mechanism. Everything about choosing a project follows from it.
Look at what is actually starred
Go and look at the trending page right now: github.com/trending ↗, set to this week.
Ignore the giant AI model releases from companies and look at the ones from individuals. Almost every one fits the same shape:
- It does one painful thing. 'Convert any PDF to clean Markdown.' 'Kill the process on a port.' 'A terminal UI for Docker.' You can say what it does in a sentence a non-programmer would follow. Not 'a modular framework for composable data pipelines'.
- You can see it working. A GIF or a screenshot at the top of the README. The visitor understands the tool before they read a word. Repos with no image at the top convert visitors to stars at a fraction of the rate, in my experience, because the visitor has to do the imagining themselves.
- The timing is right. It solves a problem people started having recently, or it's a much better version of something people search for every week. A new API, a new model, a price rise at a popular tool, a format everyone suddenly has to deal with. Tools that ride a wave get found; tools that need the wave to arrive later wait a long time.
What is missing from that page
Look at what's missing. Nobody on that page got there with 'my take on a web framework', 'a collection of useful scripts', or a rewrite of a popular tool in a different language with no new feature.
Those projects can be good. They don't get starred, because the visitor can't see in ten seconds why they'd come back.
A pattern worth naming
The tool that replaces a paid tool or a boring workflow'Diffchecker Pro but free and in the terminal.' 'The Zapier step you were paying $20 a month for, as one script.'
Those get starred and, later, they're the ones that can pay you, because you've already proved people value the job enough to pay for it.
candidates.md now. Every time something in this mission makes you think 'I could build that', write it down as one sentence. You want five to eight by step 3.If it breaksTrending is all huge AI projects from companies
Trending is all huge AI projects from companies
Where projects worth building come from
Fill the candidates file with real options, starting with the scripts you already run.
Now that you know the shape of a starred repo, you need raw material to test against it. This step fills candidates.md with real options and checks who you'd be up against.
Start on your own machine
The best candidate is usually already on your machine. Look in the folder where you keep scripts. The one you've run twenty times, copied to a colleague, and never cleaned up is a project.
You've already passed the hardest test: you use it. Add it to the file.
Four more places to look
These are in order of how good the signal is:
- Open issues on big projects. Every popular tool has a hundred open issues asking for a feature the maintainers won't build. A small tool that does just that feature, well, gets linked from the issue thread by the people who asked. Free distribution to exactly the right people.
- 'Is there a tool that' searches. On Hacker News (hn.algolia.com ↗), Reddit and Stack Overflow. The exact phrase, plus your area. Three different people asking the same question in the last year is a project.
- Paid tools with a free gap. Any SaaS whose pricing page has a feature behind the Pro tier that is, honestly, a hundred lines of code. Not to clone the product. To do the one thing in the terminal.
- A new thing everyone has to deal with. A new file format, a new API, a new model family, a new regulation. Whoever ships the clean tool first gets the search traffic for years. Check this month's release notes of the tools you use.
Check the competition
Two commands do this for each candidate. The first lists who already solves it, how big they are, and, crucially, when they last pushed. The second pulls the most discussed open issues on the biggest one, which is a list of pain nobody has fixed.
Run both commands for each candidate, replacing the search terms and the repo with your own.
Terminal (replace the search terms and repo)# Who already solves this, how big are they, are they still alive? gh search repos "json diff cli" --sort stars --limit 15 \ --json fullName,stargazersCount,createdAt,pushedAt,license \ --jq '.[] | [.stargazersCount, .fullName, .createdAt[:10], .pushedAt[:10], (.license.key // "none")] | @tsv' # Which issues are open on the big one? (pain other people have not fixed) gh issue list --repo josephburnett/jd --state open --limit 30 --json title,comments \ --jq '.[] | [.comments, .title] | @tsv' | sort -rn | head -15Each line comes back as: stars, owner/name, created date, last push date, licence.
Paste the results for each candidate into
candidates.md.
Read the dates
A 4,000 star repo that last pushed last month is a serious competitor; you need a real difference. A 2,900 star repo that last pushed two years ago is an opportunity: people still land on it from search and it no longer serves them.
A category with nothing over 200 stars means either nobody wants it or nobody has done it well yet, and the 'is there a tool' searches tell you which.
candidates.md has at least five one-line ideas, and next to each one the name, star count and last-push date of the closest existing tool (or 'none found').If it breaksgh search says I need to log in or hits a rate limit + 1 more
gh search says I need to log in or hits a rate limit
gh auth login and pick GitHub.com, HTTPS, browser. Searches count against the API limit; a few dozen is fine, hundreds in a loop is not. Wait a minute if you hit it.--jq errors about .license.key
// "none" handles it on recent gh versions. If yours is old (gh --version under 2.40), update it, or drop license from the --json list.The three tests, scored honestly
Pick one candidate by scoring, not by which one feels most exciting tonight.
You have a list of candidates. Now you cut it down to one, using a score instead of a feeling.
Three tests. Each one is a question a candidate either passes or fails, and each one predicts something specific.
Test 1: would you use it weekly?
Not 'would someone'. You. If you'd run it every week you'll keep maintaining it after the launch buzz dies, you'll notice the bugs before users do, and the README will be written by someone who actually knows the workflow.
Projects built for an imagined user get abandoned at the first boring bug.
Test 2: is it showable in a twenty second GIF?
Type a command, something visibly useful happens, done. If the demo needs an explanation, a config file, an account or a second terminal, the README will fail the ten second test and so will the launch post.
This test kills a lot of good-but-invisible ideas, like libraries with no CLI and anything whose value is 'it's faster'. Add a CLI, or add a benchmark table, or pick something else.
Test 3: does it undercut a paid product or save a named workflow?
Name the paid tool, or name the hour. 'Replaces the $12 a month JSON diff site.' 'Saves the Friday afternoon of exporting invoices by hand.' If you can't name either, you have a toy. Toys get stars sometimes, but they never pay, and this track is about ones that can.
Score the sheet
Score each candidate 1 to 5 on each test and total them, in
candidates.md, like the example below.candidates.md (example scoring)Idea Weekly GIF Undercuts/saves Total ----------------------------------------------------------------- json diff that ignores order 5 5 diffchecker Pro 15 pdf table -> csv in one go 4 5 a Zapier step 14 rename photos by GPS place 2 5 nothing paid 7 dotfiles manager (another) 5 3 nothing paid 8 Weekly: would YOU run it every week? 1 = no, 5 = daily GIF: can a stranger get it from 20 seconds of terminal? 1 to 5 Undercuts/saves: name the paid tool or the hour it saves. No name = 1Don't do it in your head, because in your head the exciting idea always wins.
Reading the result
Two rules apply. A 2 on any test is a fail even if the total is high, because each test guards against a different way of dying.
And if two candidates tie, pick the one with the smaller scope. A tool that does one thing can grow. A tool that does four things half-finished can't be launched.
jdx. Yours will be different. Keep yours. The commands are the same whatever the project.If it breaksEverything scores badly on test 3 + 1 more
Everything scores badly on test 3
My winner is a library, not a tool. It fails the GIF test
python -m yourlib input.json is enough for a GIF. Many well known libraries got their stars from a CLI wrapper that's ten percent of the code.The licence decision, and what it does to your money later
Choose a licence on purpose, because changing it later means asking every contributor for permission.
You've picked a project. Before you create anything, there's one decision to make carefully.
The licence is the one decision in this track you can't quietly revisit. Once other people have contributed code under MIT, that code is MIT forever unless each of them agrees to a change.
So decide now, with the money question in view, not after a company forks you.
Read this table, which compares the four licence options in plain English.
The four options, in plain EnglishLicence Can a company fork + sell it? Can you sell a hosted version? Can you relicence later? MIT / BSD Yes, freely Yes, so can anyone else Only with every contributor's OK Apache 2.0 Yes (patent grant too) Yes, so can anyone else Same, needs a CLA to be easy AGPL 3.0 Yes, but they must open source Yes, and rivals must open Same their changes, even over a net source theirs. Big companies work. Most companies will not. often ban AGPL deps. BSL / FSL / No, not commercially for N Yes, and only you. Not OSI You wrote the terms, yes Elastic / SSPL years, then it converts "open source". Expect flak.Now what each option means in practice.
MIT, BSD or Apache 2.0
Anyone can do anything, including sell your code, as long as they keep the notice. This is what most developers expect and what gets the most adoption: companies will use it without asking legal.
The cost is that your paid version, if you make one, competes with anyone who forks you. That's fine if your money comes from hosting, support or a Pro tier built on things that aren't in the repo (next track mission covers this).
Apache 2.0 adds an explicit patent grant, which big companies like; use it if your users are likely to be companies, MIT if they're individuals. In practice: MIT or Apache for a tool, CLI or library you want everywhere.
AGPL 3.0
Anyone can use and modify it, but if they distribute it or run it as a service, they must publish their changes under AGPL too. Companies mostly won't accept that, which is the point: they'll pay you for a commercial licence instead.
This is the dual licensing model and it works for server software (databases, dashboards, anything a company would run and modify). The cost is adoption: many companies ban AGPL dependencies outright, so a library or CLI under AGPL loses most of its corporate users.
In practice: AGPL for a server or app a company would self-host and might pay to use commercially.
Source available (BSL, FSL, Elastic, SSPL)
The code is public but commercial use, or offering it as a hosted service, is restricted for a few years, then it converts to a real open source licence. Companies like HashiCorp and Sentry use these.
For a solo project it mostly buys you flak and a 'not real open source' label on Hacker News, and it won't stop a serious competitor. Only pick it if the project is a hosted product first and open code second, and you've read the licence text, not a summary.
The contributor licence agreement (CLA) question
If you think you might ever sell commercial licences or relicence, you need every contributor to grant you the right to do so. The simplest version is a DCO (Developer Certificate of Origin: contributors add Signed-off-by to commits) plus a one paragraph CLA for anyone contributing more than a trivial fix.
Add it on day one and nobody minds. Add it after fifty contributors and you'll be chasing people on three continents.
Which one for you
- Tool or library, you want it everywhere, money will come from hosting, support or add-ons: MIT (Apache 2.0 if your users are companies).
- Server software companies would self-host and modify, money will come from commercial licences: AGPL 3.0 plus a CLA.
- A hosted product whose code happens to be public: a source-available licence, and accept the arguments.
If it breaksI want MIT adoption but AGPL protection + 1 more
I want MIT adoption but AGPL protection
What about Creative Commons or 'Unlicense'?
Create the repo with the licence and one honest line
Make the decision real: a public repo, a LICENSE file, a description that passes the ten second test.
You have a project and a licence. This step turns them into a real public repo that you can link to.
Write the description first
The description is the line that appears in search results, in the repo header, and in every link preview. It has to say what the tool does and for whom, in under 80 characters, with no adjectives.
'Diff two JSON files, ignoring key order and noise' is a description. 'A blazing fast, modern JSON toolkit' is not.
Create the repo
Write yours, then create the repo. gh will write the LICENSE file for you with the right year and your name, and clone it.
Run the commands below, replacing the name, licence and description with your own. It creates the repo, adds the licence, clones it, then shows your first commit and the top of the LICENSE.
Terminal (replace the name, licence and description)# One command: repo, licence, README, first push gh repo create jdx --public --license mit --description "Diff two JSON files, ignoring key order and noise" --clone cd jdx git log --oneline cat LICENSE | head -3Licence keys
ghaccepts includemit,apache-2.0,agpl-3.0,gpl-3.0,bsd-3-clause,mpl-2.0. For a source-available licence, create the repo without--licenseand paste the licence text from the publisher's site intoLICENSEyourself.If you're doing AGPL plus a CLA, add a
CONTRIBUTING.mdline now: 'By submitting a pull request you agree to the DCO (sign your commits withgit commit -s) and grant the maintainer the right to relicense your contribution.' You'll build the full CONTRIBUTING file in the next mission; the sentence is what matters today.
Check the name
Before you push anything else, search the name on PyPI, npm and GitHub. If it's taken on the registry you'll publish to, change it now, before the name is in a README, a GIF and a launch post.
Short, lower case, no hyphens if you can help it, and pronounceable.
Next: make the repo one people trust in ten seconds, which is the README, the GIF, the badges and the templates that turn a visitor into a star.
gh repo view --web opens your new public repo, it shows the licence in the sidebar, the description under the name, and your first commit.If it breaksgh repo create says the name already exists + 1 more
gh repo create says the name already exists
pip index versions NAME (errors if free) and npm view NAME (404 if free).I created it without --license by mistake
LICENSE, and GitHub shows a 'Choose a license template' button on the right. Pick one, commit. Then git pull locally.Your first wins
It works. Now do something with it.
Stress test the chosen project
Make the model argue against your pick before you spend a month on it:
I'm choosing an open source project to build and launch on GitHub. The idea: [one sentence]. Closest existing tools: [names, stars, last push dates]. My licence choice: [licence] because [reason]. Attack this: tell me the three most likely reasons it gets fewer than 50 stars, whether the licence choice blocks the money model I described, and one narrower version of the idea that would pass a twenty second GIF test more clearly. Be specific, no encouragement.Write the description line
Ten options, no adjectives, pick the best:
Write ten one-line GitHub repo descriptions, each under 80 characters, for a tool that [what it does] for [who]. Rules: start with a verb, name the input and the output, no adjectives like fast, modern, powerful or simple, no emojis. Then tell me which one a stranger would understand fastest and why.Undo it cleanly
How to remove everything this mission installed.
Nothing installed beyond gh.
To remove the repo, first run gh auth refresh -s delete_repo.
Then run gh repo delete OWNER/NAME --yes.
Keep candidates.md; the ideas you didn't pick are next year's projects.