Core principles

[rvagg]

Some of my thoughts, tho there is some overlap here:

• Trust, rather than walled gardens
• Empowerment, rather than bureaucracy
• Community and collaboration, rather than cliques

Discuss..

[groundwater]

From my notes:

1. trust early (or trust first)
2. mute trolling
3. promote vs. delegate
4. work in small projects

[eugeneware]

Probably need some specifics about some examples of how it's implemented. People often struggle with abstraction.

We obviously don't want to be prescriptive, as this is about principles, but giving some examples of how people are using these principles would help people "get it".

I just released my fork of the raspberry-pi wiring-pi library (https://github.com/eugeneware/wiring-pi) under open open source. And the CONTRIBUTING.md swiped from levelup is not a bad place to start.

I'll include it below for good measure:

wiring-pi is an OPEN Open Source Project

---

What?

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

Rules

There are a few basic ground-rules for contributors:

1. No --force pushes or modifying the Git history in any way.
2. Non-master branches ought to be used for ongoing work.
3. External API changes and significant modifications ought to be subject to an internal pull-request to solicit feedback from other contributors.
4. Internal pull-requests to solicit feedback are encouraged for any other non-trivial contribution but left to the discretion of the contributor.
5. Contributors should attempt to adhere to the prevailing code-style.

Releases

Declaring formal releases remains the prerogative of the project maintainer.

Changes to this arrangement

This is an experiment and feedback is welcome! This document may also be subject to pull-requests or changes by contributors where you believe you have something valuable to add or change.

[rvagg]

/cc @maxogden @dominictarr @mikeal

& please rope in any one else you know is passionate about this stuff, perhaps we also need @jlord so she can make us a badge to put on our repos?

[mikeal]

While you're already covering this implicitly there is something that needs to be explained/explored to people who first come to these ideas about shifting focus from "preventing mistakes/abuse" to "easy/fast recovery from mistakes/abuse." There is a fairly unfounded concern most people have with preventing mistakes/errors/abuse even when the worst thing that happens from such a mistake is that a test might not pass in master for an hour. If nothing is being deployed, if nothing is being automatically released as a module, the harm an erroneous contribution can cause is rather minimal but the psychology we have around error prevention hasn't changed since we were all using CVS.

We should also bring in @nslater, he's been thinking/writing about this lately too.

[groundwater]

Also @othiym23

[othiym23]

I agree with almost everything @mikeal says, with the possible caveat that life is different in a continuous deployment world. However, that's still a relatively rare thing in the OSS world.

The Knode crew might be interested in this as well.

[jlord]

:name_badge: :large_blue_circle: :beginner: Badges! :+1:

[dominictarr]

If I was to sum up how this works I'd say "decision making by consensus" instead of BDFL. Instead of a benevolent dictator, you the project "owner" acts more like a "facilitator".

Note that nearly everyone who is a contributor to levelup has also written some important module that is a key part of the level-* ecosystem.

I think that is really important, because it allows someone to prove themselves outside of their mark on the project it self, while also demonstrating their commitment to the project. You could sum this up with "modules > pull requests".

[mikeal]

I'd stay away from recommendations of either consensus or BDFL.

Having worked on larger consensus seeking projects I've experienced its limits. At small sizes with projects this focused it's likely to be fine but if a project grows in size or scope at all, or just attracts enough people, there are some unfortunate things that happen.

If a project creator wants to be the person hitting the release button indefinitely I don't see a real problem. The real thing you want to encourage is contributors to engage more often and more deeply which the whole "everything is a PR, even from the maintainer" and "add every person who successfully patches the project as a collaborator" do pretty effectively.

[groundwater]

I like how the agile manifesto doesn't outline a strict guideline, they just bring attention to tenants that they think are important. "Individuals and interactions over processes and tools" still means process is important, just that individual interactions are highly valued.

For example, "seek empowering contributors over delegating tasks". This doesn't mean you can never ask someone to do something, but it encourages you to not take that as your default position.

[nomicode]

What are you folks trying to define here?

Apache uses a discussion-lead consensus-based design-making process, with no BDFLs. I see the benefit of both approaches. The Apache model helps to ensure that a project will outlive its progenitor throwing a strop and taking harmful actions. The latter allows a single person to enforce a cohesive vision, side-stepping most problems to do with project sclerosis.

Neither of these are "core values" though. They're pragmatic issues. The one you pick is governed by your circumstances.

I really great guide for Apache-style pragmatic issues is Karl Fogel's book Producing Open Source Software. Note that this is a book. There's a lot of ground to cover if you want to do this properly. Certainly way more than you can sensibly fit into a CONTRIBUTING.md file.

If you're looking for values, I dunno, perhaps: empathy, trust, reciprocity, and the principal of charity. These all strike me as particularly important.

My first principal would be:

Your number one problem is recruitment.

You may not realise this, or believe this, but it is undoubtedly true. If your project is relying on the volunteer effort and goodwill of strangers, your biggest problem is attracting that.

This is a bigger problem that whatever technical challenges you face. But fortunately, if you get it right, the rest of the problems sort themselves out.

It goes like this: if you have an excellent bit of software but nobody who gives a crap about it, you're screwed. If you've documented it really well and written excellent tests, but nobody gives a crap about it, you're screwed. If the health of your project is dependant on your continued time and effort (either maintaining it or dealing with support tickets) you are going to burn out or get bored, and in the end you're screwed. But if all you have is a group of interested people who share your vision and want to contribute their time to make it happen: the rest takes care of itself. Code will be written, tests will be added, documentation will be contributed, and so on.

The Apache way of stating this is: community over code.

More reading:

https://blog.engineyard.com/2014/open-source-software-contribution

https://gist.github.com/nslater/9138814

My second principal would be:

Contribution comes in many shapes and sizes.

It is a common idea that OSS means coding, or contributing code. And that people contribute because they are "passionate" about it. Unfortunately, this creates an underclass of contributors who either "aren't technical enough" or are "doing it for the wrong reasons."

I'll tackle these separately:

First: Any OSS project of a certain size is going to need more than code. It's going to need docs, tests, QA, a website, design, UX, marketing, product management, project management, governance, trademark oversight, ticket triage, user support, etc, etc.

These might be handled by the same person, or by multiple people, as they flit in-between roles. But it's important to recognise that people can do one or all of these things without necessarily contributing to the code base or being able to code.

It would be absurd to say "we mustn't hire any marketing folks unless they know our code base" in a business. So why is it any less absurd to say it on an OSS project?

Further reading:

https://forrest.apache.org/committed.html

Second: If you're wealthy and have a lot of free time, it's easy to tell yourself that you're doing OSS for "passion" and that this is the only real justified reason to do OSS. Unfortunately, not everyone shares that privilege with you. People contribute for all sorts of reasons. I'd list a bunch of them, but it's basically non of your business why they're contributing.

Acknowledge this fact, and do your best to attract and recognise diverse contributions. Make it easy to contribute, provide encouragement, and don't create hierarchies of value.

Note that both of these points are essentially premised on the notion of "purity". By far, most OSS folk are a) coders and b) wealthy and have lots of free time. If you don't fit these descriptions you are tainted, lesser, other. It is absolutely about purity.

My third principal would be:

"It's easier to ask forgiveness than it is to get permission."

At Apache, we call this lazy consensus. It means, assume that people will be happy with what you want to do, and JFDI. If people aren't happy, they'll complain, and you have a discussion. Git provides us with a time-machine, so most mistakes can be undone. (And if you're doing continuous deployment, it might be good to have a dev branch to isolate mistakes.)

If you're unsure about the action you're about to take, ask people. Give them a few days to respond, and if nobody responds, assume you have permission.

This alone, this single principal, is probably one of the most important ones. It makes decision-making so much easier. And it makes it much less scary to start contributing.

Read more about this excellent concept here:

http://rave.apache.org/docs/governance/lazyConsensus.html

This is just the Apache embodiment. You can implement this principal however you like.

My fourth principal would be:

Document your decision making process, be inclusive, do everything openly, and communicate well.

Okay, that's like four principals in one. But I'm getting bored of typing.

Basically: figure out what your governance model is (even if it's just a one-liner about how disputes are resolved) and document that shit. If you've done this right, it should hopefully prevent a lot of mail churn, or ticket churn, or whatever. Your aim is to empower fast, decisive action.

Once this is done, do everything in the open. Don't make decisions at face-to-face meetups where only 50% of the contributors are invited. Don't make decisions during IRC chats late at night that 80% of the community missed.

Be inclusive. Respect that not everyone is awake all the time, and that people have personal lives. If some proposal was suggested away from whatever is your main communication hub, document it and bring it back to the whole community for review. (Even if it takes the form of lazy consensus in the form of a commit, or a notification about some action.) The goal is not to present things as a fait accompli. They are exceptionally off-putting and will harm your community.

And when you do communicate, do it well. Be kind, considerate, and respectful. Establish a code of conduct or something similar. Perhaps a contributor charter. Whatever it is. Document what you expect from people, and then hold them to it, or expel them. The principal of charity is a good one. It adds so much value to a discussion if both people are employing it.

Okay, I think I've rambled for long enough. I could literally write a book on this stuff. I hope this captures the bones of it though.

[dominictarr]

Communication skills are as, if not more, important than coding skills. Collaboration is also a skill. You practice it and improve at it.

[mikeal]

wasn't it @isaacs who put it best "empathy is a core engineering value"

[ghost]

@eugeneware Thanks! I see now how this is supposed to work.

The best practice for including the manifesto seems to be as the CONTRIBUTING document. Is this what the folks behind this idea are thinking about too?

[max-mapper]

@bucaran I have a module https://www.npmjs.com/package/collaborator that I use for this

the workflow I usually use is collaborator --npm bucaran > COLLABORATORS.md, which adds the user to github + npm and generates this:

https://github.com/maxogden/electron-packager/blob/master/collaborators.md

However I want to update it to link to openopensource.org, and update openopensource.org to have more instructions for new collaborators