Most civic open source projects don’t have a popularity problem, they have a first-contact problem. A stranger finds the repository, spends twenty minutes deciding whether it is alive and whether anyone will answer them, and leaves. Fix that first contact and the rest of the pipeline gets easier: you ship three onboarding documents, publish starter issues scoped to under an hour of work, reply within a few days, and measure how long it takes a stranger to land a first merged change.
This guide is written for the maintainer side of the table — the person answering the pull requests. Most guides on this topic are written for newcomers joining existing projects, which is a different job entirely.
Before you campaign for contributors, three things have to be true:
- Your README, CONTRIBUTING.md, and CODE_OF_CONDUCT exist, and the contributing guide answers where to start, how to open a pull request, and who to ask.
- At least five issues are labeled good first issue and each one is small enough to finish in a single sitting.
- Someone on the team answers issues within two to three days, including the ones that are just questions.
Nothing else you do matters if those three fail. You can speak at three meetups a month and each room will quietly audit the same three things.
Table of Contents
- What You Need to Attract Contributors to a Civic Open Source Project
- Step-by-Step
- 1. Define the public problem and project outcome
- 2. Show how to attract contributors with a specific first issue
- 3. Make the repository easy to evaluate and contribute to
- 4. Publish contribution guidelines and a code of conduct
- 5. Recruit through the communities where civic developers work
- 6. Support newcomers from invitation to merged contribution
- 7. Recognize contributions and keep momentum
- 8. Measure and improve the contributor pipeline
- Common Mistakes
- Frequently Asked Questions
- How can I attract non-developers to a civic open source project?
- What makes a good first issue for a new contributor?
- How many starter issues should a civic tech project prepare?
- How quickly should maintainers respond to new contributors?
- Should I use hackathons to recruit ongoing open-source contributors?
- How do I keep contributions moving after a project loses funding?
- Conclusion
What You Need to Attract Contributors to a Civic Open Source Project
A contributor arrives in stages, and each stage asks a question you either answered or didn’t. Treating recruitment as a funnel is the single most useful shift a civic maintainer can make, because it turns a vague feeling (“nobody contributes any more”) into five specific repairable failures.
| Stage | What the newcomer asks | What you need ready | Where it breaks |
|---|---|---|---|
| Discover | Does this exist and is anyone working on it? | Public repository, recent commits, dated releases, a short weekly update | The project lives in a private repo or a municipal intranet |
| Evaluate | Is it welcoming, and can I understand it? | README with the public outcome in plain language, CONTRIBUTING.md, CODE_OF_CONDUCT, license | Mission is written for council staff instead of the public |
| Choose a task | What can I realistically finish tonight? | Good first issue and help wanted labels with acceptance criteria | Issues say “improve accessibility” with no scope |
| Contribute | Will anyone actually look at this? | Working local setup path, automated checks, a named reviewer | Setup requires a database, a vendor account, or tribal knowledge |
| Get merged | How long until this lands? | A published review turnaround, friendly feedback, credit in release notes | First pull request waits three weeks for review |
| Return | Is there a reason to come back? | A public backlog, an invitation to planning calls, a path toward co-maintainer | The project goes quiet for two months after a launch |
Here is the full list of preconditions. You want all nine before you spend time on outreach:
- A one-sentence mission a non-technical person can repeat. Not a paragraph of vision, not an architecture summary. One sentence naming the public problem.
- A public repository with history. Recent commits, a release tag or two, and a README that shows a screenshot or a live demo.
- A README that says what a resident gets. People volunteer for outcomes, not for your component architecture.
- A CONTRIBUTING.md with setup steps, the branch and commit conventions, where beginner issues live, and where to ask questions.
- A CODE_OF_CONDUCT with a real enforcement contact — a name and an email address, not a placeholder.
- A license, chosen deliberately. Civic code without a license legally belongs to nobody.
- A security disclosure policy, because projects that touch 311 data or utility locations will get probed eventually.
- Five to ten starter issues, each scoped to under an hour, each with named acceptance criteria.
- Maintainer capacity of a few hours a week for triage and review. Recruiting into a black hole is worse than not recruiting at all, because it costs you a possible contributor’s trust.
That last item is the one teams skip. If nobody can respond, a friendly first issue becomes a two-week silence, and the newcomer reads that silence as a statement about the project rather than about your week.
Step-by-Step
Eight moves, in the order that works. Skipping ahead is how civic projects end up with a beautiful landing page and a backlog nobody touches.
1. Define the public problem and project outcome
Write down the civic problem in one sentence, name who feels it, and state what kind of contribution you actually want right now.
A 311 intake form that drops residents without an address in half the city’s neighborhoods is a problem sentence. “Modernizing our service request platform” is not — nobody outside your organization has an opinion about it, which is exactly the problem.
Then name the stage. Early projects need people who can set up tooling, write documentation, and define scope. Late projects need specific features. Mixing the two messages is how a conference talk lands with zero usable offers.
2. Show how to attract contributors with a specific first issue
A good first issue is one a newcomer can finish in 60 to 90 minutes, in a single pull request, without asking anyone a question. If it requires context that only exists in a maintainer’s head, it is not a first issue.
Every starter issue needs six parts:
- The outcome in one line. “Add a step-free access field to the transit stop dataset,” not “improve transit data.”
- Why it matters to a resident. One sentence connecting the task to a person who uses the thing.
- Named acceptance criteria. Specific enough that a reviewer can say yes or no without discussion.
- The files or folders involved, linked or named.
- An honest time estimate, including the learning overhead if the codebase is new to you.
- A named maintainer contact, so the person who claims it has said yes to the questions that follow.
Concrete example: a project publishing bus stop data wants to add a boolean field for step-free boarding. The issue names the schema file, shows the two example records that need updating, states that the loader test must pass, estimates 45 minutes, and assigns it to a specific maintainer. That issue is finishable. “Improve transit data quality” is not.
The trap worth naming here: an undocumented good first issue is worse than no issue. A maintainer who leaves a vague label on for a month will get half-finished pull requests from people who guessed wrong, and every one of those costs review time you were trying to save.
3. Make the repository easy to evaluate and contribute to
Separate the required path from the nice-to-have tooling, and make the required path work on a plain laptop. Most newcomers arrive on a machine with no domain credentials and no database installed, so anything requiring those is a filtering mechanism you probably did not intend.
The practical version of this is a quick-start path that a stranger can complete before deciding whether they care about your project. Clone, install, run one command, see output. If the setup needs a seeded database, vendor account, or environment file nobody has documented, fix that first and treat it as the most important contribution you will ask for all quarter.
Automate the boring parts. A lint check, a test suite, and a formatting rule take fifteen minutes to set up and save the reviewer from arguing about whitespace in every pull request. State your commit conventions in CONTRIBUTING.md and let the tooling enforce the rest.
4. Publish contribution guidelines and a code of conduct
Write the rules down where a newcomer will look before they write anything. Where do beginner issues live, how do you open a pull request, how long does review take, who do you ask when you’re stuck, and what happens if someone behaves badly.
Answer those five questions explicitly and most newcomers will never need to ask any of them. A code of conduct with a named enforcement contact is the single clearest signal in the forum conversations about welcoming projects, and it costs you an afternoon.
5. Recruit through the communities where civic developers work
Go where contributors already are, and change the message for each room rather than pasting the same announcement everywhere.
| Channel | Who it suits | First task example |
|---|---|---|
| Civic hack nights | Newcomers with no project context, and projects with a working local setup | Add one field to an open dataset during a two-hour session |
| University coding clubs and civic tech courses | Students who want portfolio-worthy work with a mentor attached | Write a scraper for one council dataset with tests |
| City and agency staff | People who know the domain and rarely think of themselves as contributors | Correct a department name or service list in a config file |
| Public-interest tech meetups and mailing lists | Maintainers-adjacent people who triage and review | Take over triage of one label for a month |
| Issue aggregators | Developers browsing by difficulty label | Tag your issues consistently so they surface |
City staff are the most overlooked group. They already understand the domain, they already know which datasets are wrong, and they rarely think of a documentation fix as an open source contribution. Ask them directly.
The message matters more than the channel. A request framed as “we need help” attracts the people with spare time, which is not the same as the people with relevant skills. Frame it as a specific need: we have an open dataset with two known accessibility gaps and no owner for them.
6. Support newcomers from invitation to merged contribution
Reply to the first message before the first pull request, even if the reply is “not this issue, try that one.” The behaviour maintainers describe as most welcoming is simple: when someone says it’s their first contribution and asks where to start, they get a specific answer and a named person.
Before the work starts: claim the issue, confirm scope in the thread, point at the right files. During: answer questions within a day, prefer pairing over silence when something is genuinely confusing. After: review within the turnaround you published, say plainly what is good about the change, credit it in the release notes, and close the loop by asking what they want to work on next.
That last sentence is where the second-commitment problem gets solved. Most drop-off happens after a first merge because nobody tells the contributor what comes next and the project goes quiet.
7. Recognize contributions and keep momentum
Keep recognition light and factual. Contributors file a contributors page, get named in release notes, and are credited on the about page — no points, no tiers, no competitive anything. Competition is exactly the wrong energy for people donating weekend hours to a public good.
Then make the path visible. Say what a co-maintainer actually does: triage a label, run the planning call, review a lane of issues. Give people a reason for the second and third contribution, and a way to earn more responsibility if they want it.
8. Measure and improve the contributor pipeline
Track a handful of numbers monthly and change one thing at a time.
- Time to first response on a new contributor’s issue or pull request. Target: under three days.
- Time to first merge from a newcomer’s first message. Target: under two weeks.
- Share of newcomers who complete a starter issue within 60 days.
- Second-commit rate — contributors active again 30 and 90 days later.
- Contributor count by track — code, data, docs, design, community, staff liaison.
- Bus factor — how many people can merge a change if the lead maintainer disappears tomorrow.
If time to first response is climbing, the problem is capacity, not recruitment, and you need a second maintainer before you need another channel. If response is fast and merges are slow, your issues are too big. If newcomers finish starter issues and disappear, you have solved the first contribution and failed the second.
Common Mistakes
Nearly every stalled civic project hits one of these, usually several at once.
| Symptom | Likely cause | Fix |
|---|---|---|
| Star count grows, pull requests do not | No scoped starter issues, or no issue tracker a newcomer can read | Publish five issues under an hour each with acceptance criteria |
| First pull requests never get reviewed | Review capacity was never budgeted | Publish a turnaround, name a reviewer per issue, add a second maintainer |
| People contribute once and vanish | No second task offered, no visible backlog | Close every merged PR with a concrete next step |
| Meetup talks produce talk but no commits | The message says “help wanted” instead of naming a task | Bring three printed, scoped tasks to every event |
| Only developers ever show up | Data, docs, and design tracks were never published | Open separate labeled tracks for data, docs, translation, and liaison work |
| Outsiders dominate governance and staff disengage | No stewardship model and no decision archiving | Publish decision records and a written stewardship plan |
| Maintainer exhausted and quiet | Triage, review, and release work is invisible labor | Delegate one lane to a co-maintainer with named ownership |
| A funder or a champion leaves and work stops | One person held all the context | Document decisions as you make them and keep two people with write access |
The pattern underneath most of these is the same: outreach was treated as the job, when maintenance is the job. A repository with a quiet maintainer looks identical to a dead one from the outside, which is why the dated weekly update matters more than any amount of promotion.
One more habit pays for itself. Before building anything new, check whether existing open source already does 80 percent of it. Extending something maintained beats starting something new, both for your contributor pipeline and for the city’s trust.
Frequently Asked Questions
How can I attract non-developers to a civic open source project?
Publish separate, labeled tracks instead of one vague help-wanted list. Data tasks look like correcting department names or adding missing dates. Documentation tasks look like rewriting a setup page. Community tasks include running a meetup or answering another newcomer’s questions. City staff are the group most often missed, and they already know the domain, so ask them directly and give them an hour-long first task.
What makes a good first issue for a new contributor?
It must be finishable in 60 to 90 minutes in a single pull request. Name the outcome in one line, connect it to a resident or user, list acceptance criteria a reviewer can check without discussion, point at the files involved, give an honest time estimate, and assign a named maintainer as contact. If finishing it would require knowledge that only exists in a maintainer’s head, it is a second issue, not a first one.
How many starter issues should a civic tech project prepare?
Five to ten is the working range. Fewer and a single unfriendly experience can sour the room. More and your maintainers inherit half-finished pull requests nobody has time to triage. Keep the list full as issues get claimed: when a good first issue drops below five, that is a signal to write more, and it is usually the least fun work on the list.
How quickly should maintainers respond to new contributors?
Under three days for the first reply, and under two weeks from a newcomer’s first message to a merged change. Publish that turnaround in CONTRIBUTING.md so people can judge your project accurately. A fast first response matters more than a fast merge, because it converts an unanswered message into a conversation, and most people will wait patiently for a merge but not for silence.
Should I use hackathons to recruit ongoing open-source contributors?
Yes, with one adjustment: build for a two-hour session, not for a weekend. Most attendees are new each week, so the setup has to be written down rather than assumed. The long-term value is not the code produced on the night, it is the two or three people who come back the following week. Close every finished task by asking what they want to work on next.
How do I keep contributions moving after a project loses funding?
Spread the context before it is gone. Record decisions as you make them, keep at least two people with write access, and write down the release process so someone else can run it. Reduce the project’s public commitments rather than freezing it: publish a short maintenance note, keep triaging, and pick a smaller backlog you can actually finish. A smaller finished backlog keeps contributors in the loop.
Conclusion
Contributors do not arrive because a project deserves them. They arrive because the project made the first hour easy and the second response fast.
Start with three things this week. Pick one public outcome and write it as a single sentence a resident would understand. Fix the quick-start path so a stranger can run it on a laptop without help. Then publish one narrowly scoped starter issue with named acceptance criteria, an honest time estimate, and your name on it.
After that, measure two numbers every month: time to first response and time to first merge. Everything else in this guide is downstream of those two. Updated for 2026.
