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.
> 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.
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.
There’s no special reason maintainers have to respond to (or even read) every comment on some years-old issue.
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.
I get you. I'm a maintainer as well. But I'm not even talking about "long resolved" issues. Last week I saw an issue created by the maintainer themselves to talk about some upcoming milestone or something, that got autolocked before the milestone got there.
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.
When I see projects on Github using the Stale Bot to automatically close issues, I don't bother looking any further. There is something so incredibly infuriating about having an issue closed automatically - when I know it is still a problem but no one has had time to look at it yet. It reminds me very much of the MSDN community threads where the accepted answer is "reinstall Windows and see if that fixes it" with hundreds of replies after that indicate it did not help.
I wonder if this would change if GitHub took the simple step of removing the PR/issue counters from the navigation.
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.
The CI is something that keeps me from contributing. I don’t say it doesn’t do it’s job and I don’t say it’s not useful. What I mean is the CI is often set up to enforce rules that aren’t clear when you create the pull request.
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.
> * 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).
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.
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).
This is the cause of many people giving up contributing to software projects. Clearly pointing to specific versions, distributions used, or (if willing to move one step ahead) prepping a VM Image or container with all the dependencies set is really helpful
To be fair, that looks like a mirror that’s been separated from its “intended” location (where there might be a link to these instructions) plus it’s a traditional “./configure && make && make install” type project anyways
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.
> Don't close bug reports just because they're old.
<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.
* 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.)
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.
That isn't closing them "just because they're old" though.
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.
Well, then the bug stays open. :shrug: Why is that so bad?
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.
It also isn't fair for people who assume a project that has a large number of closed issues is highly active, when in fact, a large number of those issues have just never seen any activity and were closed for being stale.
If the issues are closed with WONTFIX or similar status, as discussed nearby in this thread, then it should still be clear that something is going on. It is then up to the reader to decide if that something is enough for them to worry about or not.
These are all sensible rules, and I think plenty of open source projects are doing fine on this front, though its important to note that properly keeping up with these practices is a full-time job.
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.
Until recently, having a CoC in the first place is something I viewed as signalling allegiance or submission to the bully crowd you mention. Over the recent years, however, CoC seems to have become a new term for the standard rules boilerplate every community has, so I view it as neutral these days.
(Unless someone makes a big deal about adopting Contributor Covenant. That's just genuflecting to the "rail thieves".)
Nope, it's still virtue signalling. By acknowledging the need to have a paragraph of text that boils down to "play nice, or we'll take your things away", you've already given trolls too much legitimacy and power. Why is it so hard to start from a position of: assume all participants want to make the project better from the start until otherwise seen?
That leads to "the person complaining about a problem is trying to make the project worse, 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".
(That example was not referencing any particular case, BTW)
More likely that the person complaining about a social problem is actually trying to make the project worse. Like e.g. outsiders coming out of the woodwork to push CoCs on projects that don't have them.
> 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.
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.
On the flip side, I have written things that got significantly more attention that I had expected and probably came across to the project maintainers as hating on their work–and that is with multiple drafts to make it clear that this wasn't my intention. There might be random people who like to persecute individuals and their work for no good reason, but even harder to deal with are the people who have been invested in the project before and you've made unhappy; doubly so if you've reached the point where you're not interested in having certain conversations and your governance structure makes it difficult for them to feel heard. Really, this is not a simple problem and I think it's more nuanced than "people will take your Code of Conduct and use it to nitpick you and call your work stupid on the internet", when there's a whole spectrum of "this maintainer has been closing all conversations of a contentious topic by citing the governance structure" to "we made an unpopular but necessary decision that we did not explain well enough and that's causing everyone to come out of the woodwork to harass us".
Bad people cut both ways, and I think it's impossible to design any kind of document (CoC or otherwise) that can force assholes to behave nicely. All these discussions about formalizing relationships, expectations, and behaviors are in my opinion a foolish exercise of programmer logic in social situations, where you abstract away all the difficult human interactions behind something that resembles a function call and then use it everywhere. In reality, all social structures are unique, all relationships take time and effort to build, and a large amount of a programmer's effort will be spent in navigating human structures. The fantasy that you can put up a CoC so you can finally solve the human issues and get back to programming is the ultimate programmer dream, but it's not something that exists in the real world.
You're derailing a very reasonable discussion to make a political point. Instead of hiding your complaints with loaded language, be honest so we can actually discuss it on it's merits. Furthermore, it would benefit from some real-world examples. I'm frankly sick of these "The SJWs have gone too far and only care about internet cred" comments without any real analysis. It's on track to becoming much more annoying than the original problem, and stifles discussion just as much.
As it stands, all your comment is doing is contributing to the ideological echo-chamber on HN and derailing an otherwise non-political discussion.
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/
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.
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.
This study doesn't say what you think it does. Women gain significant advantage in being identified as women, except in the case of a first request, and only then by an amount on the edge of statistical significance.
https://slatestarcodex.com/2016/02/12/before-you-get-too-exc...
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.
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.
Yeah, I've been a professional dev for about 30 years and have commonly encountered a similar situation. Not always, though -- I have managed to make substantive contributions to projects.
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 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.
> 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.
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.
> "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 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.
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!
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?
They are relevant due to the "people" aspects of projects, as in, the collaborative aspects of the project. I am guessing you are pulling that line from the code of conduct portion of this post. They specifically mention having a committee of several people from different backgrounds so that the can better assess potential breaches in the code of conduct.
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.
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.
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?
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.
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.
I'm a writer who has asked similar questions in the past. I don't recall finding any slam dunk "This is how writers get involved!" solutions.
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.
Thank you for the solid advice. That was basically how I got into writing/editing as a field originally so it's good to know similar principles might apply here. An upside is that tech/engineering people (especially those involved with OSS) seem generally pretty friendly and willing to explain stuff, etc--provided that, as you said, they don't feel their time is being wasted.
The "selling" part here is convincing people that writing really matters. And you need to do it in a way that comes across as "You have a cool thing that is doing good stuff and I would like to make it betterer." You need to not make people feel insulted, which can be tricky.
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.
We need proofreaders at Standard Ebooks! You could even produce a book if you'd like, as the skills needed are basic command line familiarity, and HTML/CSS. Regex is very helpful but not required. https://standardebooks.org
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.
We would also welcome you with open arms at https://github.com/saulpw/visidata =) Send us an email, or join us on freenode, twitter, etc, if you want to help out! I would love to onboard you.
Thank you for the reply! As I said to someone else, I'll dig into this first, then reach out if I see some area where I could potentially help out. (I wasn't expecting to get so many replies to my original comment here.)
This is a similar issue for designers. Lots of open source projects desperately need UX help (or could at least benefit from a nicer website) but very few of them extend any kind of welcome to the people that could help.
funny: I read my own spec after 6 months and it struck me as the worse technical writing I had ever seen. Maybe you can take a swing at it. http://go-here.nl/ess-and-nno
I think you write very well, but I can take a swing at some minor stuff. I'll email you with suggestions/revisions when I get round to it. That's "when" not "if"--I will do it, and within 1-3 weeks, but I'm trying to finish a novel (not getting paid for it though! sounds of universe cackling in derision)
* 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.
Another is eat your own dogfood. If you enforce rules on others, enforce them on yourself. One project I keep an eye on and gave up trying to contribute to has users who berate others for something then turn around and do the same thing. If you make everyone else do code reviews. You do them too. If you want some sort of special spacing. Make the tools do it. Do not enforce them in code reviews. Teach the users how to setup the tools. Make a FAQ that shows how. Point people at it. You know where everything is, they dont.
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.
Hm, I think I know some of the cases you're thinking of. (Specifically, GNU and Stack Overflow come to mind?)
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...
The general rule is that a project shouldn't need a code of conduct. A code of conduct outlines basic decency rules in which case, if it gets to the point that the project needs to be explicit about them to keep a good ambiance, that project has deeper seated issues.
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.
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.
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:
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.
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 :(
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.
You first submit an issue where you ask if the maintainer(s) would be open for a PR. That way you wont waste any time building something that might be ignored.
The best thing is to try and find out beforehand whether your pull request will actually get looked at.
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.
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.
Try sending them an email. Be polite, and ask them if they'd be willing to take a look at your change. Make sure to explain why you made it and how it'd improve the project.
* 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!)