
Helping newcomers become contributors to open projects - rbanffy
https://journals.plos.org/ploscompbiol/article?id=10.1371%2Fjournal.pcbi.1007296
======
FeepingCreature
Some practical rules I wish projects would follow, from personal experience:

* Have a README. At the top of the README, say what the project does. Document how to build and run it.

* Make sure every artifact of the project is buildable from source. This includes project websites and binary releases. Document this process.

* Have a clear assignment of responsibilities, and respect it. If you let someone take over a task, don't micromanage them.

* Document your availability. If you have to step away from the project, put this at the top of the README, even if it's temporary. Don't drip-feed interaction - be either on or off.

* Be responsive to issues and pull requests. That doesn't mean accept everything, but answer quickly, even if just to say you need more time to look into it. Don't leave stale reviews open.

* Don't close bug reports just because they're old. A bug report is either good or bad - that is, the bug is either reproducible or it isn't. A bad bug report is bad from the start; close it quickly - or else, don't close it just because enough time has passed. (This goes doubly for bug reports with advice.)

* On documentation: one example is worth a dozen descriptions. Check if your language offers you a way to combine documentation and unittests; this is of high worth - take full advantage.

* Have a style guide. Link it in the README. This saves you time in review.

* Set up CI. Nowadays, there's plenty of free services that integrate with Github, so there's really no reason not to.

(Combo bonus: CI with style check!)

~~~
JD557
> * Have a style guide. Link it in the README. This saves you time in review.

I would go even further and recommend using some automatic style formatter.
That way, you can fail the CI step if the code is not correctly formatted and
that problem is trivial to fix (just run the formatter).

~~~
saagarjha
Plus I find that having an impersonal tool tell people that they did something
"wrong" makes them a lot more likely to fix it and still be amenable to your
future suggestions.

------
ermir
Open source projects (or any large collaboration) now have a new type of
danger that many are unprepared to handle, in that there are people online who
will shit on your work or make a giant spectacle that can ruin people just so
that they can appear good in Twitter or make some kind of name for themselves
in certain online circles. Similar to thieves who steal metal from railways,
the damage they cause is far higher to the benefit they get, and so they
should be resisted like the harmful element they are.

Sadly, having an open and explicit CoC and governance structure gives these
people a weapon to use against you. Now instead of dealing with your problem
on a case-by-case basis, you will have third parties, who otherwise have no
stake, interpreting your own CoC against you just to win some internet cred.

~~~
pjc50
It's infuriating to see those complaining about very real barriers to
contribution or actual abuses smeared as "rail thieves". For example, the
percieved gender of the submitter making a difference to pull request
acceptance rates:
[https://peerj.com/articles/cs-111/](https://peerj.com/articles/cs-111/)

~~~
megous
...by a very small margin.

It's hard to determine how maintainer preceived the submitter's gender, so
they tested for how they could have perceived instead (availability of
identifying information - and even that is very hard to determine and limited
the sample size).

Looking at the big picture, a lot of pull requests are accepted from both
genders.

I'd be concerned if the difference was >20%, but 4% with all the listed
limitations in the study doesn't get me excited.

~~~
Ididntdothis
Agreed. 4% is probably as equal as things can get realistically. You probably
can get the same margin if you compare people who wear glasses or short vs
long hair.

------
semiotagonal
Confession: I've been a professional software developer for 24 years, and I've
never been able to get my foot in the door for an open-source project (other
than my own open-sourced license stuff).

I think part of it is because the projects that are most worthwhile have no
shortage of participants, so they don't need to extend any welcome to
newcomers; and the projects that need participants often end up that way
because they're not clearly good things to be working on in the first place.

~~~
organicfigs
I've had a career about half of yours (where does the time go?) and this has
been my experience as well. I would have loved to contribute to at least half
a dozen projects in the last couple of years.

------
mlthoughts2018
I think some combinations of items 6 and 9 are often missing from projects
where there’s a quick rush to view issues and bug reports as nuisance instead
of viewing them as a lifeline of critical feedback the project needs for
survival.

I’ve seen it so many times where open source projects have critical bugs, but
the existing contributors rush to play the false defense along the lines of
“pay us if you want this fixed,” while prioritizing new features or projects
out of intellectual curiosity instead.

Obviously no contributor in an open source project _has to_ do anything. But
at some level if you’re working on the project because you care about the
project instead of burning the commons in a land grab for satisfying personal
projects, then taking priority from reported issues and even thanking people
for pointing out urgent bugs whose fixes should supercede the fun features of
some planned release has to become the expected default.

~~~
saagarjha
> Obviously no contributor in an open source project _has to_ do anything. But
> at some level if you’re working on the project because you care about the
> project instead of burning the commons in a land grab for satisfying
> personal projects, then taking priority from reported issues and even
> thanking people for pointing out urgent bugs whose fixes should supercede
> the fun features of some planned release has to become the expected default.

This is a very important point that I have generally found it hard to express,
because it seems so go counter to generally accepted view of "open source
means I owe you nothing". Which is _mostly_ true, but in certain exceptional
cases it's important to understand that popular but problematic projects suck
the air out of viable competing undertakings, and it's somewhat inconsiderate
to "squat" on something you wrote for fun at some point, promote it until it
is widely used, and then refuse to work on it anymore until people pay you
because they can't use anything else.

~~~
Hitton
I disagree. Unless the maintainer refuses to accept pull request adding new
feature/fixing the issue, there is nothing wrong about working primary on
things that concern the maintainer. Maintainer is not some sort of slave who
must rush to fulfil every wish of the user.

------
organicfigs
After being a subscriber to hn for the last decade, a post I'm affected enough
by to create an account.

After wanting to contribute to open source projects for my entire career (I've
previously worked at FAANGs and am a technical lead now), I've had 0% success
in attaining this goal. Here's been my experience:

    
    
      -reached out to the Apache Tomcat team -> silence
    
      -joined Linux Kernel Newbies -> code is such terrible quality I might unlearn somethings
    
      -joined LLVM's mailing list -> lack of issues for beginners
    

I'm now looking to contributing to Spring Boot, Apache Cassandra, or Hadoop,
but I didn't imagine it would be difficult to contribute to open source.

~~~
fourthark
You might want to look at smaller projects. But it’s generally true that
maintainers don’t have a lot of time and you might get ignored for many
reasons.

If there’s a project you use which has bugs, reporting them and submitting
fixes is always a great way to start!

------
Odenwaelder
Genuinely interested: How are gender identity, race, ethnicity, etc. of any
relevance in Open Source Projects? Is this a regular topic of discussion
besides the code?

~~~
twoquestions
If you look at some other stories, specifically "Text Rendering Hates You" and
"Text Editing Hates You Too", working with non-English languages in text is
tough, and it gets harder the farther from English you're working with.

Considering ethnicity is the only way to prioritize issues like that.

~~~
Odenwaelder
I wasn't thinking of the end user experience, but more of the developer
experience. I'm wondering why such a clause is even written in CoCs.

------
spats1990
offtopic-ish but maybe somebody sees it: can anyone recommend places around
the web to look for open source projects where I can help out as a writer? I
write and edit professionally but am bad at code beyond some 101-level Java,
and beyond that the usual html/css. I've always appreciated well-written help
docs, manuals, FAQs, etc of any kind and would like to help out if I can and
hopefully learn some things while doing so, even if it's just low-level stuff
like proofreading. Can anyone point me in the right direction?

~~~
CrazyStat
I've seen several sites that list open source projects looking for help (see
e.g. [1]), but I'm not aware of any focusing specifically on documentation.

My advice would be to look at the documentation for projects that you use or
like. The state of documentation in open source projects overall is not great,
so probably you can find a project that could use some help. It might take a
while to develop a good working relationship with the developers, but once
they realize you're a good writer and serious about helping hopefully they'll
give you enthusiastic support.

[1] [https://www.firsttimersonly.com/](https://www.firsttimersonly.com/)

~~~
spats1990
Thank you for the link and good general advice. I've been using linux on and
off for a while (these days just mint/tina) for a while so I'll try to work
out if/how I can help in that sphere.

------
rurban
Beware, pitfalls.

* Make governance explicit: Mostly backfires.

* Have and enforce a code of conduct: Mostly backfires.

All the recent dramas were entirely caused by having explicit governance and
code of conduct bylaws, which would not have happened (and didn't happen)
without these before. It only encourages public fights over these.

~~~
matheusmoreira
Yeah. I've witnessed so many controversies I started archiving and collecting
them. Code of conduct enforcement is flawed to say the least.

~~~
at_a_remove
I would be interested in seeing these.

My naive hope is that a code of conduct could be crafted with defensive
measures to at least mitigate such problems, but that is probably hopeless in
the face of bad actors.

~~~
matheusmoreira
> I would be interested in seeing these.

I have some links bookmarked:

[https://github.com/nodejs/TSC/issues/325](https://github.com/nodejs/TSC/issues/325)

[https://archive.is/XcxSf](https://archive.is/XcxSf)

[https://archive.is/YnGGz](https://archive.is/YnGGz)

[https://archive.is/EJmJ7](https://archive.is/EJmJ7)

That directly followed a failed attempt at enforcement that led to a fork:

[https://web.archive.org/web/20170821212745/https://github.co...](https://web.archive.org/web/20170821212745/https://github.com/nodejs/TSC/issues/310)

This article covers the whole thing:

[https://theoutline.com/post/2206/the-node-js-code-of-
conduct...](https://theoutline.com/post/2206/the-node-js-code-of-conduct-
diversity-tech)

An HN discussion:

[https://news.ycombinator.com/item?id=15101668](https://news.ycombinator.com/item?id=15101668)

> My naive hope is that a code of conduct could be crafted with defensive
> measures to at least mitigate such problems

The problem isn't the letter of the law, it's that the rules don't seem to
apply to certain groups of people.

------
Sir_Cmpwn
There's just one rule which does it for me:

Thanks for your bug report! The next step is to submit a patch fixing the bug.
If you need help, ask questions in our chat room at...

------
mikece
While this is meant for open source and mostly remote workers, I can’t help
thinking how much better the applications and teams with which I’ve worked
over the years if they followed this advice.

------
rezeroed
Don't steal their PRs and commit them as your own.

~~~
rezeroed
Voted down? It's happened to me twice. Explain yourself (fat chance).

------
StavrosK
A few friends and I created a community to help maintain abandoned OSS
projects, and one of our goals is to foster newcomers and help them make their
first contributions to open source projects.

If you want to start (or know someone who does), please point them to our
page:

[https://www.codeshelter.co/mentorship/](https://www.codeshelter.co/mentorship/)

------
DoreenMichele
_projects should not just say that they welcome new members: they should make
a proactive effort to foster positive feelings in them. One way to do this is
to post a welcome message on the project’s social media pages, Slack channels,
forums, or email lists. Projects might also consider maintaining a dedicated
"Welcome" channel or list, where a project lead or community manager writes a
short post asking newcomers to introduce themselves._

I have not found it especially helpful to have a place set aside for the
express purpose of letting newcomers introduce themselves and be officially
welcomed to the community. This is an extremely shallow way to do this and I
don't believe it's especially effective.

(I am not an open source maintainer. I do have moderating experience.)

It's generally better to "greet people at the door." In other words, the first
time a new person says something, engage them. Be polite. Be respectful. Try
to keep things on topic.

If they ask a question and it doesn't get a reply within X period of time,
reply to it even if you don't know the answer. Don't make them feel ignored.
Replying may bump it and get it answered. Even if it doesn't, they won't be
afraid to keep talking.

"The silent treatment" should be used to intentionally starve problem behavior
of attention (a la _Don 't feed the trolls_). It shouldn't be seen as a valid
response to a newcomer just because you don't know what say to them.

 _Keep knowledge up to date and findable_

You can't document everything and newcomers don't necessarily read your
extensive documentation.

I would focus on making sure some key stuff is covered and occasionally reread
it to make sure it doesn't say anything egregiously wrong and misleading
because things have changed. Minimal, accurate documentation is more useful
than extensive inaccurate documentation.

They recommend that you have and enforce a code of conduct, then admit
_Research on these is still in its infancy_.

If you are in an influential position, get with the person in the mirror
regularly. If you see a problem behavior cropping up regularly, wonder what
you are doing that is inadvertently causing that to somehow be acceptable and
make sense to people.

Watch your sense of humor. It is often a source of unintended consequences.

Codes of Conduct, like Rules of Law, basically are their most useful when
something has gone very, very wrong and a third party needs to arbitrate. They
mostly aren't that useful for fostering good behavior. You mostly foster good
behavior by how you comport yourself.

Too much focus on Codes of Conduct can be counterproductive and can signal "We
are so badly behaved, we need it constantly explained to us what good behavior
is supposed to look like."

It's good to have some guidelines and best practices, but be careful that you
don't spend an excess of time overly focused on nominally rooting out some
particular evil.

Think of it this way:

If you feel you need to state up front in your dating profile "No Rapists!!!!"
then maybe that dating site should be skipped altogether. It's fine to do a
little polite hand slapping occasionally to establish where to more clearly
draw that line, but you shouldn't need to aggressively focus on things that
should "go without saying."

Ironically, a genuinely healthy and well mannered environment has a certain
tolerance for interpersonal friction. It needs to be a place where hand
slapping can occur without turning into major drama.

An environment where everyone needs to walk on eggshells is not a polite
environment. It's a terrifying and very unhealthy environment.

------
matheusmoreira
Detailed mailing list instructions would be very nice. I read all I could find
about them and still screwed up when I tried to participate in one.

~~~
saagarjha
There's unfortunately a lot of song-and-dance that goes into joining a new
mailing list, and unfortunately the fact that they go to _everyone_ and often
have a different etiquette than other types of online communication can make
them a bit scary :(

------
adultSwim
This is great advice for any organization with a large volunteer community.

------
Kenji
What do you do when the owner of the repository just ignores your pull
request? I put hard work into some improvements and I would also change and
adapt them to the repository owner's liking, but he just doesn't reply. He
doesn't even say he doesn't have time, he's just completely absent. (And yes,
the library is very popular and used by many) It's annoying because I depend
on that library, so now I have to depend on my own branch which is obviously
not main.

~~~
matheusmoreira
I had a similar experience. I sent in a bug fix and some new features. The
maintainer partially accepted my fix and ignored the other patches. After many
messages and additional work, he just said the features would not be added to
the project and that I was free to maintain my own version.

Sometimes it's better to just let go.

~~~
Double_a_92
They probably had their reasons for that... at least you got a closure.

That's why it probably good to talk about bigger fixes first, so you can align
your visions.

