
Announcing Open Source Guides - bkeepers
https://github.com/blog/2318-announcing-open-source-guides
======
neom
I've said it a billion times on HN and I'll say it a billion more, we are
super fortunate to have the work that Nadia Eghbal does.

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...](http://www.fordfoundation.org/library/reports-and-
studies/roads-and-bridges-the-unseen-labor-behind-our-digital-infrastructure)
[2]: [https://changelog.com/rfc](https://changelog.com/rfc)

------
njt
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/](http://producingoss.com/)

------
chuhnk
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.

------
wimagguc
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".

~~~
steveklabnik
> 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.

------
josh64
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!

~~~
joshdotsmith
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.

------
EternalData
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).

------
trengrj
They are quite good but why do I get the feeling the domain name was bought
before the idea was decided on.

~~~
bkeepers
PR where domain was purchased: [https://github.com/github/open-source-
guide/pull/90](https://github.com/github/open-source-guide/pull/90)

------
morinted
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.

~~~
jdc0589
ditto. I was thinking it would be along the lines of Digital Ocean's curated
how-to's/guides.

~~~
andrenotgiant
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...](https://github.com/thewhitetulip/build-app-with-python-
antitextbook)) 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...](https://www.digitalocean.com/community/tutorials/contributing-
to-open-source-getting-started-with-git) and this
[https://www.digitalocean.com/community/tutorials/maintaining...](https://www.digitalocean.com/community/tutorials/maintaining-
open-source-software-projects)

~~~
jdc0589
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.

------
ryan_lane
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.

~~~
joshdotsmith
Do you have anything you can share at all?

------
gravypod
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:

    
    
        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. "
    

That doesn't really, for me, explain what it is or why we need one. To be
fair, it follows up with this:

    
    
        " 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. "
    

That to me doesn't make sense. I've never really seen an enviroment that would
reasonably make someone "unhappy" or "drained" by my standards nor have I ever
seen a reason why someone should want to "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.
    

My concern is the vaugness that is nesessitated by such a controling document.
Perticularly I'm afraid of the "Advocating for, or encouraging, any of the
above behavior." clause. I completely belive people have the right to say all
of those things. In effect I am "advocating" for the existance of speech from
bad actors indirectly by saying "I may not agree with what you have to say but
I entierly support your right to say it". If I advocate for ALL free speech
then I must advocate for ALL free speech. Not "Free Speech __* ".

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.

~~~
ryan_lane
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.

~~~
gravypod
> Restriction of freedom of speech only applies to the government and not to
> communities or private organizations

That's not how morals work.

~~~
javra
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.

~~~
gravypod
> 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.

------
rofex
Good move. Should help newbies and fence-sitters participate more!

