Get Started
Open source that pays

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.

50 minBeginnerFreeFree mission

What you'll do

Learn what gets starred

Study this week's trending page and spot the three things the individual-made repos share.

Score your candidates honestly

Find real ideas, check the competition with two commands, and score each idea on three tests.

Choose a licence and create the repo

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
Before you start
  • A GitHub account and the gh CLI 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
01/05What gets starred, and what doesn't0 done
STEP 01 of 05~7 min

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

  1. 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.

Tip
Open a text file called 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.
Checkpoint
You've looked at this week's trending page and written, in your own words, which three features the individual-made repos on it share.
If it breaksTrending is all huge AI projects from companies
Trending is all huge AI projects from companies
Switch the language filter to Python, Go, Rust or TypeScript and the date to 'this week'. The individual projects show up a few rows down. Also try star-history.com ↗ on any repo you admire to see whether it grew in a spike (a launch) or a line (search traffic). Both are fine; the shape tells you how it was found.
Still stuck? Ask the community
STEP 02 of 05~10 min

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.

  1. 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 -15

    Each line comes back as: stars, owner/name, created date, last push date, licence.

  2. 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.

Warning
Competition is not a reason to stop. It's proof people want the job done. The reason to stop is a well maintained competitor you can't name one concrete improvement over. 'Mine is in Rust' is not an improvement unless the existing one is slow enough that users complain.
Checkpoint
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
Run 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
Some repos have no licence and the field is null; the // "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.
Still stuck? Ask the community
STEP 03 of 05~10 min

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

  1. 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 = 1

    Don'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.

Tip
The one that scored 15 in the example is the worked example for the rest of this track: a JSON diff that ignores key order, called jdx. Yours will be different. Keep yours. The commands are the same whatever the project.
Checkpoint
One candidate is circled, it scored 3 or more on every test, and you can say in one sentence what paid tool it undercuts or what workflow it saves.
If it breaksEverything scores badly on test 3 + 1 more
Everything scores badly on test 3
Then you're picking toys. Go back to the 'paid tools with a free gap' and 'open issues on big projects' sources in step 2; those produce candidates with money or time already attached. A weekend of searching beats a year of maintaining something nobody needed.
My winner is a library, not a tool. It fails the GIF test
Give it a tiny CLI that exercises the main feature on a file. Even 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.
Still stuck? Ask the community
STEP 04 of 05~12 min

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.

  1. Read this table, which compares the four licence options in plain English.

    The four options, in plain English
    Licence         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.
Warning
Don't write your own licence, don't add 'no commercial use' to MIT, and don't leave the LICENSE file out. 'No licence' means nobody can legally use your code at all, and most companies' tooling will flag it. Pick from the list.
Checkpoint
You've written one line under your chosen project: the licence, and the money model it leaves open (for example 'MIT, money from a hosted version and paid support').
If it breaksI want MIT adoption but AGPL protection + 1 more
I want MIT adoption but AGPL protection
You can't have both; that's the trade. The usual compromise is MIT for the core tool and a separate, closed or AGPL repo for the server, dashboard or enterprise features. That's open core, and mission 6 covers how to split it without annoying your users.
What about Creative Commons or 'Unlicense'?
Creative Commons licences aren't written for code and don't handle patents or warranties; avoid them for software. Unlicense and CC0 put the code in the public domain, which some jurisdictions don't recognise. MIT does the same job and everyone's lawyers already understand it.
Still stuck? Ask the community
STEP 05 of 05~8 min

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.

  1. 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 -3

    Licence keys gh accepts include mit, apache-2.0, agpl-3.0, gpl-3.0, bsd-3-clause, mpl-2.0. For a source-available licence, create the repo without --license and paste the licence text from the publisher's site into LICENSE yourself.

    If you're doing AGPL plus a CLA, add a CONTRIBUTING.md line now: 'By submitting a pull request you agree to the DCO (sign your commits with git 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.

Checkpoint
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
You already own a repo with that name, or you're inside another repo's folder and it's confused. Run it from your home folder, or pick a new name. To check a name on the registries: pip index versions NAME (errors if free) and npm view NAME (404 if free).
I created it without --license by mistake
In the repo on GitHub, click Add file, name it LICENSE, and GitHub shows a 'Choose a license template' button on the right. Pick one, commit. Then git pull locally.
Still stuck? Ask the community

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:

Prompt
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:

Prompt
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.

Next mission · Open source that paysA repo people trust in ten seconds: README, GIF, badges, templates, releases
→