Helping newcomers become contributors to open projects
journals.plos.org
journals.plos.org
* 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!)
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).
And don't lock them as stale once closed. Holy shit, it's infuriating seeing projects abuse what is essentially an anti-harrasment tool to prevent people from pinging old issues with relevant information. Especially if said old issue is a top hit on Google for some set of keywords.
Losing the context of the old issue often kills contributions outright.
Even though I'm maintaining Lock Threads [1], I sometimes shake my head when I come across a closed issue that was locked by it, but I also have to admit that all I want is to ask a question quickly and get the information I need, without considering how my shortcuts affect maintainers.
There may be times when there's a legitimate reason for commenting on a long-resolved issue, but unfortunately most of the comments on closed issues are low effort support requests. Locking them as resolved is the best solution we have so far to avoid spending our time retriaging closed issues.
Yes, it's just misconfiguration, but when you're configuring these tools you're never thinking about the damage the autolocks do to your project if you're not very careful with the settings. Remember, the people just get turned off from contributing. They don't stick around to give feedback on this being the root cause.
Hell, I never did, and I'm very vocal about autolocking being toxic.
If maintainers have their email set up to pester them every time someone writes a comment anywhere, that’s the fault of the email setup, not the commenters’ fault.
Instead of locking the topic, consider just leaving a note that future discussion there is likely to be ignored by the team, and then letting users continue to discuss workarounds, etc.; often the issue tracker is the only kind of discussion/help forum available to project users.
This, especially in non-web repos (C/C++) is common mistake of READMEs and docs.
Let's take an example of XFCE-WM project [0]. The main README does not include any information how to compile it, nor provides any link to the documentation how to build this very specific code. If you will google it you might find following wiki page [1], which is general for all repositories. In the COMPOSITOR [2] file you might notice some information about flags that you can provide during building, and that's great such doc has been created, but except that document I couldn't find any information how "fresh contributor" would like to debug and test some change in code that he made in the cloned repository. Download and install some linux distro on virtual machine and then invest (1h+) to configure it accordingly to run it there? Use Xephyr (I guess "fresh contributor" has never heard about this tool)?
In my honest experience, the "how to build" step is probably included in many of repositories, but the "how-to-run" is usually lacking in READMEs and it is what I really would like to see in complex projects (e.g. desktop environment).
> 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.
One more thing related to docs and "how-to-build-&-run" thing. Let's say the project owner have some critical accident that made him unavailable to push progress of development forward for few months or longer. If there isn't any knowledge shared (docs, other contributors) then I guess the project will be stalled and possibly forgotten if there is no clear incentive to use alternative methods of repo maintenance (e.g. fork).
[0]: https://github.com/xfce-mirror/xfwm4
[1]: https://docs.xfce.org/xfce/building
[2]: https://github.com/xfce-mirror/xfwm4/blob/master/COMPOSITOR
Yes, sure - it's a mirror, but take a look at original source [0][1]. I haven't found much information about "build & run" either.
> it’s a traditional “./configure && make && make install” type project
Yes, it is but you are talking about "building" not "running", which is also important process in terms of development. Also, deduction (from source code) what kind of combination of commands might be is a no-go argument for many would-be contributors (I looking at few friends who fall in love in npm start), not saying it requires some experience in specific tooling (here, how to build C projects), which not everyone has.
I disagree... lots of bug reports actually are not bad at all, but are also not something that you want to prioritize. If multiple parties look at a bug report repeatedly for years and do not prioritize it, its a pretty good sign that it is something that will not be done. Closing bugs that aren't going to be done is a good thing, but it isn't always such an obvious decision on day 1. Of course, they can always be reopened (or duplicated) if the situations change.
The only reason I can see to close old bugs is that a project wants to make it seem like it has fewer issues than it does, and hopes that users won't notice the issue.
It is a little more than that in many cases. People judging a project overall by the number of open bugs reports, no matter how minor, isn't really fair if there is considerable development on more important bugs/features/other elsewhere in the project.
That is closing them in a "WONTFIX" state. This is perfectly valid for minor irritations or matters that the maintainers don't agree are bugs at all, though some (entitled) bug reporters will take umbrage with it especially if they've taken the time to actually produce a good bug report rather than just a vague "X doesn't work" or "Y breaks Z".
If closing in a WONTFIX state, a brief explanation added to the ticket is a good idea, to reduce the risk of future time wasted because it is simply reopened as a new bug. For instance: you might be closing it in that state because it will become irrelevant shortly due to other work (perhaps the feature is changing considerably which will render the issue moot), because you don't consider it a bug (i.e. behaviour by design) or fixing to some satisfactory standard is something there isn't time for (i.e. your "not ever likely to be a priority" status). In the "not ever likely to be a priority" case, perhaps suggest that a PR addressing the issue matching your coding standards (assuming you have them documented) would be welcome, though only do that if such a PR would have a change of being given the relevant assessment time.
Because I can’t see a reason for automatically dismissing issues you ignore as stale, unless you think the issue count is bad optics for your project.
As well as github’s issue triage piece being non-existent. All you’ve got is a list that shows you 20 things at a time, and it suffers from the social media effect where anyone can add bullshit memes to the thread once someone on twitter has directed the mob to it.
You don’t really see that happen so much outside of github.
I’ve a pull request to Ansible that’s open for ~ 2 years now and I keep on doing commits just to satisfy the CI without getting any actual feedback from the Ansible maintainers whether or not my pull request will be accepted.
And just yesterday I opened a pull request on the Azure cli and the CI pipeline forbids pull requests to master without telling first time contributors the accepted workflow.
My contribution is just a small typo fix in a help text, but adding a sentence of how to create a good pull request in the issue template would actually go a long way.
<rant> Somebody should tell this to Kubernetes developers.
Also, thanks to Github's braindead UI of marking every issue as either "Open" or "Closed", once I click a Google link to any Kubernetes issue I have no idea if (1) the issue is closed because it was fixed in the latest version (so I have to upgrade), or (2) the issue is closed because it turned out to be invalid (so I have to search for something else), or (3) the issue wasn't solved at all, but Kubernetes team decided to tell everybody "Haha we don't care. And to really drive the point home that we don't care, we're gonna auto-close it for lack of activity."
So I have to scroll all the way down and read the discussion. Sorry, that was my pet peeve #168 for Kubernetes. Carry on.
</rant>
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.
(Unless someone makes a big deal about adopting Contributor Covenant. That's just genuflecting to the "rail thieves".)
(That example was not referencing any particular case, BTW)
> so all we have to do is ban the person who said that <prominent contributor> groped them at a conference and we can get back to work
Yes. Such an issue should be brought to the police, not be posted on an issue tracker for rallying social media lynch mobs. Cases of exaggerating or straight up lying about sexual harassment in order to remove or destroy someone are common enough, and consequences of a mistaken judgement severe, so the presumption of innocence is very important.
... who will often ignore it.
> Cases of exaggerating or straight up lying about sexual harassment in order to remove or destroy someone are common enough
Are they?
Which is still not a justification for making public accusations of illegal, perhaps criminal behavior on a project issue tracker or mailing list.
> Are they?
Acknowledged that it may happen in some cases, and that is extremely regrettable and frustrating. However, I believe that is no justification for jumping straight to what I consider pretty much "mob justice".
Investigations still matter. Facts still matter. You fundamentally have a right to confront your accuser and challenge the evidence in a court of law, before a judgement and potential punishment is rendered upon you. You don't get the same benefit when you are being tried in the court of public opinion (social media). I get suspicious when people skip the court of law route and only pursue the court of public opinion route.
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.
As it stands, all your comment is doing is contributing to the ideological echo-chamber on HN and derailing an otherwise non-political discussion.
But I don’t think the problem is widespread; it’s just people getting excited about bad things that happened.
So I agree: more analysis, more facts please. It’s a good conversation to have; let’s keep it substantive.
Also, not having one also makes lots of people rally against you. You can't win on the CoC front
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.
But, to be honest, I've entirely given up on contributing to such projects a few years back, because so many have become unpleasant to work with due to nontechnical problems.
I largely only contribute to my own projects these days.
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.
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.
Does that happen? Sounds pretty extreme, I hope you are exaggerating.
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
If there’s a project you use which has bugs, reporting them and submitting fixes is always a great way to start!
Considering ethnicity is the only way to prioritize issues like that.
As for if this is a regular topic of discussion besides the code, that obviously varies wildly, but I believe it's being discussed more these days.
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.
I have had some luck with suggesting better wording for projects submitted via Show HN. Some of that has been adopted and I've been sincerely thanked a few times. I've documented a little of that as part of a kind of portfolio.
I haven't tried super hard to pursue this. If you want to get involved in earnest, you need a little luck (plus some quiet, patient persistence). You should look for situations with an extensive need for writing help plus good personal rapport between you and one or more key people.
That's basically how you get involved in something when they aren't really looking for you. You identify a need you can meet, then try to establish those personal connections that aren't overly personal, but are personable enough where you can have good and useful conversations about stuff not currently on their radar without them giving you the cold shoulder because they see you as a waste of time.
I think that's the biggest thing I wrestle with is convincing people I have something of value to offer without sounding like "You suck!" It's really tricky when it's knowledge work.
The other thing about writing technical documentation is you have to understand the tech some to talk about it. I occasionally do resume work and I mostly do that for experienced tech people who probably know me through HN in most cases. I can edit their resumes even though I'm not a serious programmer because I have some idea what the hell they do for a living.
This is a really big thing for the tech world. Communicating well means you first need to understand the topic and the tech world routinely beats its head against a wall because managers and salespeople and so forth don't actually understand the tech well enough to be genuinely effective. It leads to lots of "They did this stupid thing because they honestly have no idea what the tech actually does."
This seems to be a factor in some of the debacles where some startup company has stuck "AI" in the name, absolutely can't deliver on that promise and they are getting sued because of it.
A lot of "tech" solutions are like that scene in Men in Black 2 where they open the mail sorting machine and inside is a guy with many arms flinging mail as fast as he can.
Many non-technical people honestly don't know the difference between a box of people and an actual machine-based solution. If you are crowd sourcing work from many remote workers and getting results on a website, they just see the website and go "Well, neat! Computers are amazing!"
So be prepared for writing technical documentation to be hard at first and involve a lot of research. But if you get good at it, you might find that people will seek you out because a lot of writers simply aren't qualified to communicate on the subject. They don't have the background knowledge.
Documentation is one of the most important things for the well-being of a project. Your contributions would be extremely valuable. So if you think what we do is worthwhile, please get in touch.
Full disclosure: I am the maintainer
So don't short-sell yourself. :)
* 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.
But don't you think these were (at least in part) only the visible outbreaks of conflicts that had already been simmering for a long time? If that is so, introducing an explicit governance/CoC may have been a long overdue step that ended up breaking some crockery, but only because it wasn't enacted early enough...
Codes of conduct are great when the etiquette is ambiguous. Open source projects are not one of those.
When the users are in the wrong, you should be able to kick them out uncontroversially. And when the maintainers are in the wrong... They tend to ignore their own CoC anyway. Speaking from experience, I've tried contributing to a particular PSF project in the past, adding a feature to support a use case the maintainer did not like (supporting tab indent option in a code formatter), which was ignored and closed; and when I pointed out to the maintainer that his behaviour was in breach of the CoC, that too was ignored. What are you gonna do? In the end I had to fork the project.
Another pitfall I see is what I call 'claiming with neglect' where a user will claim something then let no one else touch it, usually in a pull request that someone put a bunch of time into. But then not do what they said they were going to do. Two years later the pull request dies on the vine and nothing changes. The person who made the request usually just wanders off due to lack of feedback.
Another is letting pull requests sit for years. Just set a max timeframe. If it does not go in that time close it. Do leave the person hanging. I get that happens on a dead project. But on a project that is obviously active? Give that pull request some love. Close it, tweak it, or merge it (something!).
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.
I have some links bookmarked:
https://github.com/nodejs/TSC/issues/325
That directly followed a failed attempt at enforcement that led to a fork:
https://web.archive.org/web/20170821212745/https://github.co...
This article covers the whole thing:
https://theoutline.com/post/2206/the-node-js-code-of-conduct...
An HN discussion:
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.
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...
If you want to start (or know someone who does), please point them to our page:
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.
Sometimes it's better to just let go.
That's why it probably good to talk about bigger fixes first, so you can align your visions.
It's also not so uncommon for maintainers to just get burned out and disappear for a while, so you might get a reply still.
I made a directory[1] where you can filter projects by things like how long maintainers take to reply, although this isn't too helpful for the specific project in question of course.