Add vision to the project readme and clean up CONTRIBUTIONS.md

[maxmeyer]

Summary

Add vision to show why we do things in the aruba project.

Details

This PR adds our vision to explain why we work on aruba. To explain why we add features and why implement them in the given way.

Motivation and Context

This should make it easier for new cucumber's to understand our motiviation. I added this after a discussion with a user. Please also see this issue #361.

How Has This Been Tested?

No, this IS the test. If this doesn't work, we can remove it from the readme.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.

[maxmeyer]

@mattwynne @aslakhellesoy WDYT about such a thing? Does this makes sense to you or is it just (too much) "bla"?

@e2 Would a vision help you to understand the motivation behind "aruba" better? I want to try to start addressing the "issues" on a higher level.

I know "visions" maybe on a (too) "abstract" level, that developers don't feel very interested in / not that comfortable with them since they're quite blurry. I tried to find a balance between abstract / specific.

[e2]

@e2 Would a vision help you to understand the motivation behind "aruba" better?

Definitely! People want to get a "sense" of a project before committing.

Without a vision 2 "bad things" can happen:

1. A lack of a vision may encourage the wrong kinds of people (who weren't a good fit in the first place) - no harm done, it's better for people to know what the expectations are up front. Even if they don't agree. Especially if they don't agree.
2. A lack of vision may lead to aligned people misunderstanding/misinterpreting the intentions and making assumptions - without even reaching out for an explanation. So good, aligned people may "fall off" before even getting on.

I know "visions" maybe on a (too) "abstract" level, that developers don't feel very interested in / not that comfortable with them since they're quite blurry.

Developers are very interested in "abstract", or they wouldn't be developers. But they do want everyone else to be specific, so there are lots of challenges there. Especially helpful developers want problems expressed in specifics - at least something they can estimate/evaluate or even just "guess".

E.g. There are 2 extremes in software development: designing rockets with "one shot only" or countless billions go down the drain ... and ... pretty much the web, where anything goes, as long as it's within budget. Anything.

Those extremes usually have completely opposite rules. They're incompatible. So a vision helps people know which extreme they're on.

E.g.: do they think this project a good thing to get involved? Or does it have "more bureaucracy that for nuclear silo software" and isn't "exciting enough" ... or is it "too chaotic, unstable, hard to plan things through, and agree to anything longer than a day".

A vision also shows how (and if) a team is committed. Because it may not be fun to be the only one committed. Or, it might be the opposite - that contributors have to "prove" their commitment over a longer period of time. Which may also not be fun for "causal" developers just "flirting" to see if they can improve something here and there without being "married" to a project.

Some want the community, and neglect the code. Some just want to coding to "escape" something ... and neglect the community. Neither is wrong or wrong if there's some kind of valuable contribution going on.

Also, projects go through different stages. So this might be the "right" stage for someone ... or not.

It might be good to jump in now. Or, it might be better to just "wait". Or it might just be better to fork off and maybe someday see if there's enough "overlap" to make something useful.

Developers are constantly asking themselves questions like: "should I bother with this? Or will it backfire?".

Any info that makes the above clearer can only help.

[e2]

Given what I said above, here's what this tells me:

1. Help our users to build better command line applications
2. Make creating documentation for command line simple and fun
3. Support the cucumber community in its effort to create a specification for all official cucumber implementations

And my thoughts/reaction:

1. Yes, I'm in 100%. I'd really like to see not only RVM support working, but additional steps for helping with development and the whole life cycle. I want to make this part better.
2. I have zero interest in this. I prefer to "prevent" the need for all documentation if possible. Just my preference.
3. I have zero interest in this too. I used to be very interested in Cucumber, but I didn't find it paying off when it comes to the downsides. I prefer to see things crashing quickly and closer to the real problem. The worst thing for me is having 5 API layers and a nice UI standing between me and a problem that should be quickly fixed. I'm more interested in making a "good engine" and then using it to power something bigger.

I don't know if that's clear from my side, but it's my take based on just those 3 points.

[maxmeyer]

1. Yes, I'm in 100%. I'd really like to see not only RVM support working, but additional steps for helping with development and the whole life cycle. I want to make this part better.
2. I have zero interest in this. I prefer to "prevent" the need for all documentation if possible. Just my preference.
3. I have zero interest in this too. I used to be very interested in Cucumber, but I didn't find it paying off when it comes to the downsides. I prefer to see things crashing quickly and closer to the real problem. The worst thing for me is having 5 API layers and a nice UI standing between me and a problem that should be quickly fixed. I'm more interested in making a "good engine" and then using it to power something bigger.

@e2 I think it'll be ok if users are not interested in all of those 3. If only one is suitable for them they might be interested to get involved. :-) I'm quite happy that you start working with that energy on aruba's code base.

Based on your other feedback I tweaked some more parts of our "documents". WDYT about those changes?

[maxmeyer]

I added a new milestone org-1.0.0 to keep track of improvements the organisation of the project.

[e2]

You have two groups of people to communicate to here:

1. Users
2. Contributors

So for everyone you want to explain "what it's like":

1. For users, what they can expect (good job here)
2. For contributors, what they can expect during PR reviews

You also want to "hint" at what kind of people are involved, especially when it comes to contributors.

For users, you want to let them get a sense of what "support" is like. Can they ask for help, to what extent, how quickly will they get a reply, are they met with patience, friendliness, kindness, etc.

You have to pretty much decide what kinds of users you want, because you can't please everyone.

Contributors want to quickly "judge" whether PRs will be a pleasure or a pain in the ass (from their perspective). Being "unclear" means people will just assume the latter. So listing your "priorities" for accepting/rejecting patches helps people get PRs right the first time.

E.g. you might want to hint what's more important: fixing bugs vs contributor experience vs quality of documentation. (There's no "right" answer here).

[e2]

One suggestion: discriminate heavily. (Sounds bad, I know - but it's essential).

Decide on what users/contributors you DON'T want.

You don't have to write about it - it's just so people have a consistent experience and know what to expect.

It's only fair, because if someone isn't a good fit, at least they're "warned" they're going to have a hard time. Also, people who "fit" are going to spend less time worrying how they're going to be treated.

E.g. "I just want to fix some documentation - will they accept my patch or will they be too busy working on other stuff?". Based on what you wrote, the answer would be a strong "yes".

And, e.g. "I'd like to quickly add an API specific for my project - will this be possible without forking?" and the answer will likely be a strong "no". And that's fair, because instead of working on a PR, they can just open an issue with a question to "get a sense" if there's a chance the PR can get accepted and on what conditions.

Discriminating is good, because everyone is super-busy these days.

Trying not to "exclude" or "not hurting" anyone only means you end up rejecting and "hurting" everyone.

[maxmeyer]

@e2 I addressed things mentioned by you. I think this will work for now. Other things will be addressed by document.

[maxmeyer]

Thank you very much for your helpful feedback.