Announcing Open Source Guides(github.com)
github.com
Announcing Open Source Guides
https://github.com/blog/2318-announcing-open-source-guides
27 comments
Also check out the book "Producing Open Source Software: How to Run a
Successful Free Software Project" by Karl Fogel.
He just finished up the 2nd edition and made it freely available online: http://producingoss.com/
He just finished up the 2nd edition and made it freely available online: http://producingoss.com/
Building a successful and sustainable long term open source project is hard. It's nice to see GitHub contributing some knowledge share that will hopefully be useful to those wishing to get started or validate what they've learned the hard way.
I love the looks, the texts and just how much effort Github put into these docs. After having read quite a few pages, I'm just a bit puzzled: who are these guidelines for?
Corporates usually have their own open-source guidelines (we had one at my R&D jobs even before Github existed), and these docs are a bit overdone for the tiny projects that lone devs usually put online. You know what I mean, for the ones where a single-line guideline would have been enough: "Please, if you don't want to write a readme, at least add some in-line comments".
Corporates usually have their own open-source guidelines (we had one at my R&D jobs even before Github existed), and these docs are a bit overdone for the tiny projects that lone devs usually put online. You know what I mean, for the ones where a single-line guideline would have been enough: "Please, if you don't want to write a readme, at least add some in-line comments".
> who are these guidelines for?
My understanding (you'll find some of my work quoted here, and I contributed a small amount before that this was public) is that this resource is for individuals who want to be involved in open source, either as contributors or maintainers, to learn about how it works. That is, a lot of open source development is sort of a shared, "oral" history; this resource spells out a lot of things that those of us who have been in the scene for a while just know, but you have to learn at some point.
My understanding (you'll find some of my work quoted here, and I contributed a small amount before that this was public) is that this resource is for individuals who want to be involved in open source, either as contributors or maintainers, to learn about how it works. That is, a lot of open source development is sort of a shared, "oral" history; this resource spells out a lot of things that those of us who have been in the scene for a while just know, but you have to learn at some point.
This is an excellent starting resource. As one of the maintainers of a popular open source project I was wondering how I could get help with the project by attracting new contributors as I work full time and find the balancing act hard.
Users have previously enquired about donations and I didn't know the best way to set up the project to accept them in a responsible manner. This guide points me in the right direction!
Users have previously enquired about donations and I didn't know the best way to set up the project to accept them in a responsible manner. This guide points me in the right direction!
Do you mind sending me an email sometime? You can find one in my HN profile. I'm really curious to hear about what you've done to find maintainers and how you've thought about tackling the fundraising issue.
I've been looking for something like this. It's not even the content that really matters, it's more the extra push it gives people to contribute to open source projects. I often find a lot of people don't know where to even start (myself included early on).
[deleted]
They are quite good but why do I get the feeling the domain name was bought before the idea was decided on.
PR where domain was purchased: https://github.com/github/open-source-guide/pull/90
I thought this was going to be a GitHub implementation of GitBook. Excitement fell when I clicked through. However, anything that makes getting into open source easier is good in my books.
ditto. I was thinking it would be along the lines of Digital Ocean's curated how-to's/guides.
Ahhh that's interesting, especially because to a certain extent, people are already writing content on github organically (like this https://github.com/thewhitetulip/build-app-with-python-antit...) but I always assume these are also hosted elsewhere, even if it is a github pages domain.
What additional features or functionality would you want github to add to make writing/hosting guides better?
Also, DigitalOcean has "contributing to open source" stuff like this https://www.digitalocean.com/community/tutorials/contributin... and this https://www.digitalocean.com/community/tutorials/maintaining...
What additional features or functionality would you want github to add to make writing/hosting guides better?
Also, DigitalOcean has "contributing to open source" stuff like this https://www.digitalocean.com/community/tutorials/contributin... and this https://www.digitalocean.com/community/tutorials/maintaining...
the reason the ones on digital ocean are good is because 1) reasonably consistent format, at least visually anyway. 2) curated. they actually review submissions. 3) if your guide gets accepted, you get some DO credit or something. so, there's an incentive for quality material.
This guide is really, really awesome. I maintain similar guides for companies and am excited to see a public version of most of what I've written.
Do you have anything you can share at all?
Ok so this is slightly off topic but I guess it still relates because it's on the this page. This document has a section on "Code of Conduct"s and it proposes this question and following answer:
I feel that if you have an open source project it's a rag-tag bag of programmers, designers, and technical people who are working on something that they should all be interested in. The discussion on the modes provided by an open source project's forums or whatever should be purely technical. When you have a purely technical medium I don't see how anyone would be upset by a convorsation.
We all know what the COCs look like, I'm pretty sure we all know how they can be misued, but one thing we don't all know is why you'd need to use it in the first place (at least I don't).
If you're a BDFL and you have some opinion that disagrees with another person you can just act like a human: talk it out or ignore them. I don't see why we need to, or even should, codify that.
If I'm missing something please do correct me on this.
PS: I just noticed some people might not understand what I mean, so I'll try to explain it with an example. I belive in freedom of speech and press. So a common expression is "I may not agree with what you have to say but I entierly support your right to say it". In Django's COC you will find this section (I'll do my best to format it):
This includes the vile behavior of bad actors whether or not I like it.
Can I be banned for saying "I may not agree with what you have to say but I entierly support your right to say it"? Well as the current COC for Django stands, certiantly a case can be made for my advocacy, to some degree, of these horrible things I don't like.
Q: " Why do I need a code of conduct? "
A: " A code of conduct is a document that establishes expectations for behavior for your project’s participants. Adopting, and enforcing, a code of conduct can help create a positive social atmosphere for your community. "
" Codes of conduct help protect not just your participants, but yourself. If you maintain a project, you may find that unproductive attitudes from other participants can make you feel drained or unhappy about your work over time.
A code of conduct empowers you to facilitate healthy, constructive community behavior. Being proactive reduces the likelihood that you, or others, will become fatigued with your project, and helps you take action when someone does something you don’t agree with. "
I feel that if you have an open source project it's a rag-tag bag of programmers, designers, and technical people who are working on something that they should all be interested in. The discussion on the modes provided by an open source project's forums or whatever should be purely technical. When you have a purely technical medium I don't see how anyone would be upset by a convorsation.
We all know what the COCs look like, I'm pretty sure we all know how they can be misued, but one thing we don't all know is why you'd need to use it in the first place (at least I don't).
If you're a BDFL and you have some opinion that disagrees with another person you can just act like a human: talk it out or ignore them. I don't see why we need to, or even should, codify that.
If I'm missing something please do correct me on this.
PS: I just noticed some people might not understand what I mean, so I'll try to explain it with an example. I belive in freedom of speech and press. So a common expression is "I may not agree with what you have to say but I entierly support your right to say it". In Django's COC you will find this section (I'll do my best to format it):
Be careful in the words that you choose. We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to:
Violent threats or language directed against another person.
Discriminatory jokes and language.
Posting sexually explicit or violent material.
Posting (or threatening to post) other people's personally identifying information ("doxing").
Personal insults, especially those using racist or sexist terms.
Unwelcome sexual attention.
Advocating for, or encouraging, any of the above behavior.
Repeated harassment of others. In general, if someone asks you to stop, then stop.
This includes the vile behavior of bad actors whether or not I like it.
Can I be banned for saying "I may not agree with what you have to say but I entierly support your right to say it"? Well as the current COC for Django stands, certiantly a case can be made for my advocacy, to some degree, of these horrible things I don't like.
Restriction of freedom of speech only applies to the government and not to communities or private organizations. Just because you believe everyone should have the right to say these things wherever they want doesn't make it true. You're free to say these things, but you're not free from the repercussions of saying them in a private community.
If you're unhappy that a community implements a code of conduct, you're free to not join it, and if you're someone who does any of these things I'd recommend you not join any open source community.
Really, seriously, the entire point of a code of conduct is to tell people they can't be shitty people and continue to be in the community and it shows people joining the community that it cares enough about shutting down trolls that they're willing to advertise that they're willing to shut down trolls.
If you're unhappy that a community implements a code of conduct, you're free to not join it, and if you're someone who does any of these things I'd recommend you not join any open source community.
Really, seriously, the entire point of a code of conduct is to tell people they can't be shitty people and continue to be in the community and it shows people joining the community that it cares enough about shutting down trolls that they're willing to advertise that they're willing to shut down trolls.
> Restriction of freedom of speech only applies to the government and not to communities or private organizations
That's not how morals work.
That's not how morals work.
But freedom of speech is a political concept which only makes sense for states. Any smaller community can add rules to the ones that hold by law. Be it you bowling team or software company. That's why clubs have by-laws/charters.
> But freedom of speech is a political concept which only makes sense for states
No, it's a principle. Morals and principles are not necessarily politics.
> Any smaller community can add rules to the ones that hold by law. Be it you bowling team or software company. That's why clubs have by-laws/charters.
This has nothing to do with my principles. My principles dictate that they are allowed to self-govern provided they don't, themselves, revoke the freedoms of anyone unable to consent.
From my (and other's) principles we can derive laws.
This works as follows: "Murder is unethical in specific cases because <insert logic> so we should <insert law> and if this is broken <insert punishment>".
As you can see, the law is derived from the principle. The law is an enforcement of the group's principles. Laws don't generate principles, principles and morals generate laws.
This can easily be proven by asking the following: If freedom of speech is only a principle to be upheld by government, then what about the other essential freedoms of humanities? The right to life, liberty, and the pursuit of happiness? If the common man does not need to uphold freedom of speech principles then surely it is ok for us to encroch on other freedoms such as life. It's surely ok for us to kill or own people. It's ok for us to steal. It's ok for us to pollute and otherwise destroy the sources of happiness that the world provides.
These principles, that are self evident, that all men are created equal, that all have a right to life, liberty, and the pursuit of happiness are what our laws are derived from. It's not only our government's job to uphold these principles. It's for every citizen of any civilized society to uphold them. If we loose the cornerstone right of humanity, the right to free discorse, then humanity looses all rights.
Just because something is legal doesn't make it right, and just because something is illegal doesn't make it wrong. Legality SHOULD be an expression of the common shared morals of all of our society. Sadly that is being lost and many people like you are now holding opinions that are the exact opposite of what was just stated. You seem to be of the mind that things that just because something is legal it makes it right, and just because somethign is illegal it makes it wrong. Why? I don't understand this. Just because "the government said so" isn't really a good reason.
No, it's a principle. Morals and principles are not necessarily politics.
> Any smaller community can add rules to the ones that hold by law. Be it you bowling team or software company. That's why clubs have by-laws/charters.
This has nothing to do with my principles. My principles dictate that they are allowed to self-govern provided they don't, themselves, revoke the freedoms of anyone unable to consent.
From my (and other's) principles we can derive laws.
This works as follows: "Murder is unethical in specific cases because <insert logic> so we should <insert law> and if this is broken <insert punishment>".
As you can see, the law is derived from the principle. The law is an enforcement of the group's principles. Laws don't generate principles, principles and morals generate laws.
This can easily be proven by asking the following: If freedom of speech is only a principle to be upheld by government, then what about the other essential freedoms of humanities? The right to life, liberty, and the pursuit of happiness? If the common man does not need to uphold freedom of speech principles then surely it is ok for us to encroch on other freedoms such as life. It's surely ok for us to kill or own people. It's ok for us to steal. It's ok for us to pollute and otherwise destroy the sources of happiness that the world provides.
These principles, that are self evident, that all men are created equal, that all have a right to life, liberty, and the pursuit of happiness are what our laws are derived from. It's not only our government's job to uphold these principles. It's for every citizen of any civilized society to uphold them. If we loose the cornerstone right of humanity, the right to free discorse, then humanity looses all rights.
Just because something is legal doesn't make it right, and just because something is illegal doesn't make it wrong. Legality SHOULD be an expression of the common shared morals of all of our society. Sadly that is being lost and many people like you are now holding opinions that are the exact opposite of what was just stated. You seem to be of the mind that things that just because something is legal it makes it right, and just because somethign is illegal it makes it wrong. Why? I don't understand this. Just because "the government said so" isn't really a good reason.
[deleted]
The Code of Conduct at Contributor Covenant is specifically designed to force politics on other people inside and outside FOSS projects. Its creator describes the ideology here:
https://medium.com/rx3-magazine/why-hackers-must-welcome-soc...
ESR represented meritocracy instead in the post below. One was written to counter the other but don't remember what order. I link to an example Code of Merit as well to show how simple it is:
http://esr.ibiblio.org/?p=6918
https://medium.com/@jmaynard/a-contribution-policy-for-open-...
The manipulative tactics they use are often called SJW by critics. The combo of pushers aiming for political dominance and sophist tactics to achieve goals means anything like that CoC should be rejected totally and quickly. It will just be leverage later as it's intended to be. A good write-up on how that works where they act like their claims aren't controversial but argue with or censor each other all the time on it is below. So is an attack on Ruby community by non-contributors pushing the CoC & politics with Coraline herself dropping smears in support. Starts nice enough but they show true colors as resistance continues. ;)
http://slatestarcodex.com/2014/07/07/social-justice-and-word...
https://github.com/opal/opal/issues/941
Note to all: This is a draft of a reference reply on this issue since it comes up a lot. Many people new to CoC's don't know they're openly meant to be political. If any have a clearer set of links, I'm interested in them. If you like this set as an intro, tell me so I can turn it into a Pastebin or something.
Edit to add: Anyone wanting to discuss this further just email me or something so this topic doesn't get polluted with politics.
https://medium.com/rx3-magazine/why-hackers-must-welcome-soc...
ESR represented meritocracy instead in the post below. One was written to counter the other but don't remember what order. I link to an example Code of Merit as well to show how simple it is:
http://esr.ibiblio.org/?p=6918
https://medium.com/@jmaynard/a-contribution-policy-for-open-...
The manipulative tactics they use are often called SJW by critics. The combo of pushers aiming for political dominance and sophist tactics to achieve goals means anything like that CoC should be rejected totally and quickly. It will just be leverage later as it's intended to be. A good write-up on how that works where they act like their claims aren't controversial but argue with or censor each other all the time on it is below. So is an attack on Ruby community by non-contributors pushing the CoC & politics with Coraline herself dropping smears in support. Starts nice enough but they show true colors as resistance continues. ;)
http://slatestarcodex.com/2014/07/07/social-justice-and-word...
https://github.com/opal/opal/issues/941
Note to all: This is a draft of a reference reply on this issue since it comes up a lot. Many people new to CoC's don't know they're openly meant to be political. If any have a clearer set of links, I'm interested in them. If you like this set as an intro, tell me so I can turn it into a Pastebin or something.
Edit to add: Anyone wanting to discuss this further just email me or something so this topic doesn't get polluted with politics.
> The Code of Conduct at Contributor Covenant is specifically designed to force politics on other people inside and outside FOSS projects. Its creator describes the ideology here:
That's insane. Why would anyone want to force politics into a technical discussion. I can't think of a single place where the Red or Blue on my ballot would influence my software development prowess. Same for nationality or opinions on social matters.
Some of the things in this article make no sense.
> There are those who firmly believe that the politics of social justice have no place in the world of open source. They think that the injection of political ideologies is a corruption of the apolitical nature of free software.
> From the onset open source has been inherently a political movement, a reaction against the socially damaging, anti-competitive motivations of governments and corporations. It began as a campaign for social liberty and digital freedom, a celebration of the success of communal efforts in the face of rampant capitalism. What is this if not a political movement?
> All political movements start with an ideology. But when they are set in motion this ideology may become obscured. It is crucial that we constantly scrutinize the manifestation of our principles to ensure that the lofty goals of our ambitions are in line with our actions.
This is going to be a really really good read. Thanks for the share nick!
That's insane. Why would anyone want to force politics into a technical discussion. I can't think of a single place where the Red or Blue on my ballot would influence my software development prowess. Same for nationality or opinions on social matters.
Some of the things in this article make no sense.
> There are those who firmly believe that the politics of social justice have no place in the world of open source. They think that the injection of political ideologies is a corruption of the apolitical nature of free software.
> From the onset open source has been inherently a political movement, a reaction against the socially damaging, anti-competitive motivations of governments and corporations. It began as a campaign for social liberty and digital freedom, a celebration of the success of communal efforts in the face of rampant capitalism. What is this if not a political movement?
> All political movements start with an ideology. But when they are set in motion this ideology may become obscured. It is crucial that we constantly scrutinize the manifestation of our principles to ensure that the lofty goals of our ambitions are in line with our actions.
This is going to be a really really good read. Thanks for the share nick!
"Why would anyone want to force politics into a technical discussion."
My thoughts exactly. Their belief is that forcing their kind of politics creates an inclusive space that all people feel welcomed in and then contribute to the project. All people like them anyway. As in the other reply to you, they consider anyone else to be "assholes" doing "hate speech," holding back minorities, etc. The woman behind that was hired or consulted for Github's new moderation effort which enforces their philosophy on top of otherwise good practices (eg no harassment/trolling). That's part of why these this stuff is in the guide.
You're welcome for the links. Email me any feedback you have so I can continue curating.
My thoughts exactly. Their belief is that forcing their kind of politics creates an inclusive space that all people feel welcomed in and then contribute to the project. All people like them anyway. As in the other reply to you, they consider anyone else to be "assholes" doing "hate speech," holding back minorities, etc. The woman behind that was hired or consulted for Github's new moderation effort which enforces their philosophy on top of otherwise good practices (eg no harassment/trolling). That's part of why these this stuff is in the guide.
You're welcome for the links. Email me any feedback you have so I can continue curating.
Good move. Should help newbies and fence-sitters participate more!
If you've not read Roads and Bridges: The Unseen Labor Behind Our Digital Infrastructure I highly recommend you do [1]. Her podcast is also great [2].
[1]: http://www.fordfoundation.org/library/reports-and-studies/ro... [2]: https://changelog.com/rfc