Welcoming Newcomers

you only have one chance to make a first impression

Learning Objectives

Explain why a CONTRIBUTING.md file matters even for a two-person project.
Evaluate a CONTRIBUTING.md for a real newcomer's experience.
Produce a draft CONTRIBUTING.md that a stranger could follow.

Before

Two external contributors had submitted pull requests to the simulator six weeks before this workshop. Jess knew their names: one was a postdoc in Finland who had added support for a new habitat type, and the other was a grad student in New Zealand who had fixed a bug in the climate data parser. Both were good changes. Jess had meant to review them, but she'd been busy.

Both contributors had gone quiet. When Jess emailed to apologize, the Finnish postdoc replied politely that she'd already implemented the feature in her own fork. The New Zealand student didn't reply at all.

Feeling Welcome

[Steinmacher2015] studied why newcomers abandon open source projects and found that the majority of drop-off doesn't happen because of technical problems, but because no one responds, the response is confusing or unwelcoming, or there is no clear path to the next step. The contributor from Finland had run into all three. She'd read the CONTRIBUTING.md (one sentence: "We welcome pull requests"), had questions about coding style, had waited three weeks for someone to answer her question, and then solved the problem herself. The technical barrier was never the issue.

A useful CONTRIBUTING.md removes these barriers before they become drop-off points. It needs to say:

How to set up the development environment (exact commands, not "install dependencies")
How to run the tests and what the expected output looks like
What kinds of contributions are and aren't welcome
How to submit a pull request and what happens next
Who to contact when stuck, and a realistic response time

A useless CONTRIBUTING.md contains aspirational language about community values, instructions that assume a specific operating system or Python version, and setup steps that haven't been tested in eight months. Most projects have the useless version.

The "good first issue" label is a promise. If you use the label and a newcomer spends six hours on it only to discover it requires understanding three years of architectural decisions, you have broken the promise. Before adding the label, have someone who hasn't worked on that part of the code estimate how long it would take them. If they can't estimate, the issue isn't ready for the label.

Legitimate Peripheral Participation

Legitimate peripheral participation is the idea that newcomers ease into a community of practice by starting with small, low-risk tasks that still contribute something real [Sholler2019, Wenger1999]. Jess asked Ren to write one test before touching any production code. He learned the project structure, got a successful pull request merged, and felt like a contributor before tackling a new feature. The test took him two hours; the next pull request took him thirty minutes.

A Code of Conduct is not optional. Its existence signals what kind of project this is, and so does its absence. But a Code of Conduct that doesn't describe who handles complaints, and how, is decoration. Do cannot write the enforcement mechanism when you need it; you need to write it before [Aurora2019].

After

After the two abandoned pull requests, Jess rewrote the CONTRIBUTING.md from scratch. She had an LLM follow the steps on her computer, which was successful, then asked a colleague who had never seen the project to try it on a clean machine. He got stuck at step three: the instructions said pip install -e . but didn't mention that the project required GDAL, which can't be installed with pip on most systems. Jess had forgotten she'd installed GDAL separately years ago. The test took forty minutes and found a bug in the instructions that three years of contributors had silently worked around.

Exercises

Draft Your CONTRIBUTING.md (10 min)

You have a template with section headers already in place:

Setup
Running the tests
Submitting changes
What we're looking for
Getting help

Prompt an LLM like this:

Write a CONTRIBUTING.md for a Python research software project called [name] that [one sentence about what it does]. The main dependencies are [list]. Tests are run with [command]. The project is hosted on GitHub. Be specific about setup steps.

Ask yourself, "Could a competent Python programmer who has never seen this project follow these instructions successfully?"
Edit the draft generated by the LLM. Replace anything generic with specifics. Mark any section you can't fill in yet for further work.

Fresh Eyes Test (8 min)

Swap your draft with a partner.

(5 min) What command should you run first? What does a successful test run look like? Who do you contact if you get stuck?
(3 min) Ask your partner one "what do I do if…" question that their document doesn't answer.