Open Stack

On 2014-02-12 15:34, Adrian Otto wrote:
> On Feb 12, 2014, at 12:41 PM, Ben Nemec <openstack at nemebean.com>
>  wrote:
> 
>> On 2014-02-12 13:48, Adrian Otto wrote:
>>> On Feb 12, 2014, at 10:13 AM, Ben Nemec <openstack at nemebean.com>
>>> wrote:
>>>> On 2014-02-12 09:51, Jesse Noller wrote:
>>>>> On Feb 12, 2014, at 8:30 AM, Julie Pichon <jpichon at redhat.com> 
>>>>> wrote:
>>>>>> Hi folks,
>>>>>> Stefano's post on how to make contributions to OpenStack easier 
>>>>>> [1]
>>>>>> finally stirred me into writing about something that vkmc and 
>>>>>> myself
>>>>>> have been doing on the side for a few months to help new 
>>>>>> contributors
>>>>>> to get involved.
>>>>>> Some of you may be aware of OpenHatch [2], a non-profit dedicated 
>>>>>> to
>>>>>> helping newcomers get started in open-source. About 6 months ago 
>>>>>> we
>>>>>> created a project page for Horizon [3], filled in a few high level
>>>>>> details, set ourselves up as mentors. Since then people have been
>>>>>> expressing interest in the project and a number of them got a 
>>>>>> patch
>>>>>> submitted and approved, a couple are sticking around (often 
>>>>>> helping out
>>>>>> with bug triaging, as confirming new bugs is one of the few tasks 
>>>>>> one
>>>>>> can help out with when only having limited time).
>>>>>> I can definitely sympathise with the comment in Stefano's article 
>>>>>> that
>>>>>> there are not enough easy tasks / simple issues for newcomers. 
>>>>>> There's
>>>>>> a lot to learn already when you're starting out (git, gerrit, 
>>>>>> python,
>>>>>> devstack, ...) and simple bugs are so hard to find - something 
>>>>>> that
>>>>>> will take a few minutes to an existing contributor will take much
>>>>>> longer for someone who's still figuring out where to get the code
>>>>>> from. Unfortunately it's not uncommon for existing contributors to 
>>>>>> take
>>>>>> on tasks marked as "low-hanging-fruit" because it's only 5 minutes 
>>>>>> (I
>>>>>> can understand this coming up to an RC but otherwise 
>>>>>> low-hanging-fruits
>>>>>> are often low priority nits that could wait a little bit longer). 
>>>>>> In
>>>>>> Horizon the low-hanging-fruits definitely get snatched up quickly 
>>>>>> and I
>>>>>> try to keep a list of typos or other low impact, trivial bugs that
>>>>>> would make good first tasks for people reaching out via OpenHatch.
>>>>>> OpenHatch doesn't spam, you get one email a week if one or more 
>>>>>> people
>>>>>> indicated they want to help. The initial effort is not 
>>>>>> time-consuming,
>>>>>> following OpenHatch's advice [4] you can refine a nice "initial
>>>>>> contact" email that helps you get people started and understand 
>>>>>> what
>>>>>> they are interested in quickly. I don't find the time commitment 
>>>>>> to be
>>>>>> too much so far, and it's incredibly gratifying to see someone
>>>>>> submitting their first patch after you answered a couple of 
>>>>>> questions
>>>>>> or helped resolve a hairy git issue. I'm happy to chat about it 
>>>>>> more,
>>>>>> if you're curious or have any questions.
>>>>>> In any case if you'd like to attract more contributors to your 
>>>>>> project,
>>>>>> and/or help newcomers get started in open-source, consider adding 
>>>>>> your
>>>>>> project to OpenHatch too!
>>>>>> Cheers,
>>>>>> Julie
>>>>> +10
>>>>> There’s been quite a bit of talk about this - but not necessarily 
>>>>> on
>>>>> the dev list. I think openhatch is great - mentorship programs in
>>>>> general go a *long* way to help raise up and gain new people. Core
>>>>> Python has had this issue for awhile, and many other large OSS
>>>>> projects continue to suffer from it (“barrier to entry too high”).
>>>>> Some random thoughts:
>>>>> I’d like to see something like Solum’s Contributing page:
>>>>> https://wiki.openstack.org/wiki/Solum/Contributing
>>>>> Expanded a little and potentially be the recommended “intro to
>>>>> contribution” guide -
>>>>> https://wiki.openstack.org/wiki/How_To_Contribute is good, but a 
>>>>> more
>>>>> accessible version goes a long way. You want to show them how easy 
>>>>> /
>>>>> fast it is, not all of the options at once.
>>>> So, glancing over the Solum page, I don't see anything specific to 
>>>> Solum in there besides a few paths in examples.  It's basically a 
>>>> condensed version of https://wiki.openstack.org/wiki/GerritWorkflow 
>>>> sans a lot of the detail.  This might be a good thing to add as a 
>>>> QuickStart section on that wiki page (which is linked from the how 
>>>> to contribute page, although maybe not as prominently as it should 
>>>> be).  But, a lot of that detail is needed before a change is going 
>>>> to be accepted anyway.  I'm not sure giving a new contributor just 
>>>> the bare minimum is actually doing them any favors.  Without letting 
>>>> them know things like how to format a commit message and configure 
>>>> their ssh keys on Gerrit, they aren't going to be able to get a 
>>>> change accepted anyway and IMHO they're likely to just give up 
>>>> anyway (and possibly waste some reviewer time in the process).
>>> The key point I'd like to emphasize is that we should not optimize 
>>> for
>>> the ease and comfort of the incumbent OpenStack developers and
>>> reviewers. Instead, we should focus effort on welcoming new
>>> contribution. I like to think about this through a long term lens. I
>>> believe that long lived organizations thrive based size and diversity
>>> of their membership. I'm not saying we disregard quality and
>>> efficiency of our conduct, but we should place a higher value on
>>> making OpenStack a community that people are delighted to join.
>> 
>> I'm not disagreeing, but there has to be a balance.  tldr: there are a 
>> lot of pitfalls in the submission process, and if they aren't 
>> well-documented they're going to frustrate new contributors to no end.
>> 
>> For example, let's say someone reads through just the Solum page (if 
>> they follow the link to GerritWorkflow then they're back to the big, 
>> scary documentation we have now).  They try to submit their change.  
>> It fails because they have no ssh keys on Gerrit so they can't 
>> connect.  Casual contributors probably give up here because they 
>> followed the instructions and they didn't work.
>> 
>> But let's assume they visit review.openstack.org and get an ssh key 
>> registered on Gerrit.  They try again.  This time they fail due to an 
>> unsigned CLA.  Okay, sign the CLA (assuming their employer doesn't 
>> restrict them from doing that, but that's a whole other discussion).  
>> Hooray, Gerrit will accept their submissions now!
>> 
>> But wait, now they put the entire commit message in one block of text 
>> because they don't know any better.  Let's say worst-case-scenario 
>> that they're submitting to a project that's gated on Tempest so it 
>> takes an hour or more for Jenkins to vote, and an hour later it fails 
>> due to the pep8 violation in the commit message (note that there 
>> doesn't seem to be a mention of running tox before submitting in 
>> either set of documentation).  Fair enough, they fix their commit 
>> message to have a first line <72 characters as pep8 tells them to.
>> 
>> They submit again.  Their submission sits for a week because the 
>> project they're working on has a long review queue.  Maybe a reviewer 
>> comes along and notices their commit message has an improper bug 
>> reference and -1's.  At this point I'd be throwing things around the 
>> room. :-)
>> 
>> Granted, this is a very pessimistic scenario, but I'd bet most new 
>> contributors hit some subset of these issues on their first submission 
>> because our existing documentation is either too concise and doesn't 
>> cover these steps, or is too long and rambling and therefore they miss 
>> important details.  As I said below, as simple as possible, but no 
>> simpler.  Where that line is probably varies by person, but I think we 
>> can all agree we're missing the mark right now.
> 
> Agreed.
> 
>>> Focused efforts like the one outlined by Julie Pichon are exactly 
>>> what
>>> OpenStack needs to make on-boarding smoother, and more pleasant. 
>>> Thank
>>> you Julie for sharing what you are learning, and helping us improve.
>> 
>> Absolutely +1!
>> 
>>>> That said, the GerritWorkflow page definitely needs some updates and 
>>>> maybe a little condensing of its own.  For example, do we really 
>>>> need distro-specific instructions for installing git-review?  How 
>>>> about just "Install pip through your distro's package management 
>>>> tool of choice and then run pip install git-review"?  I would hope 
>>>> anyone planning to contribute to OpenStack is capable of following 
>>>> that.
>>> Optimize public facing documentation for throughput of attracting new
>>> members, not maximizing efficiency of the existing ones. We can 
>>> decide
>>> how to deal with internal inefficiency as it presents as a problem.
>>> Our default mode should be welcoming.
>> 
>> No argument here, but I still think we should be able to assume a 
>> certain level of competency in our prospective contributors.  In a 
>> process as complex as the one we're dealing with, a digression to 
>> discuss every possible way a package might be installed is just noise 
>> IMHO.  Right now the length of GerritWorkflow is not welcoming.
>> 
>>>> I guess my main point is that our contributing docs could use work, 
>>>> but there's also that "as simple as possible, but no simpler" thing 
>>>> to consider.  And I certainly don't like that we seem to be 
>>>> duplicating effort on this front.
>>> All efforts that result in more open source, and more community
>>> participation should be encouraged. Don't worry as much about
>>> duplication of recruiting efforts. Trying a few different approaches,
>>> and seeing what works best is a great approach to something like 
>>> this.
>>> Attracting a community is not a science. It's an art form. Making art
>>> is about trying a bunch of things, and seeing what works best.
>> 
>> Sure, but it's a wiki.  Rather than creating a completely separate 
>> page that almost entirely duplicates an existing one, why not fix up 
>> what we already have so everyone benefits?  Right now the Solum page 
>> is only useful if you're looking for Solum information, and the 
>> instructions there apply to every single OpenStack project.  And if 
>> someone disagrees with your changes they're welcome to make their own. 
>>  It's the wiki way. :-)
> 
> I thought you were somehow suggesting that OpenHatch was a bad idea,
> which struck me as alarming. I see now that you are referring to the
> wiki content. We can work to merge some of that.

Yeah, sorry.  I kind of hijacked this email thread to rant about 
documentation.  OpenHatch definitely sounds interesting. :-)

> 
>> I guess I see the Solum page as a sort of cheat-sheet for people who 
>> have already been through the longer form Gerrit workflow page, and I 
>> do think that would be useful.  I just think it would be useful to 
>> everyone, not only Solum developers.
> 
> Back in October, when we made the contributor page, we only
> contemplated being an OpenStack Related project. So, we needed a place
> to indicate what our governance setup is (since we have no TC, no
> Board, etc.). Members of the project wanted to keep things simple. We
> were rapidly attracting new contributors from outside the OpenStack
> ecosystem, and tried to summarize the contribution process so that
> people could conceptualize it. I received guidance from stakeholders
> (one even from the OpenStack Board of Directors) that it was important
> to show that Solum was a Stackforge project, and not part of
> OpenStack's core/integrated family of projects. What you see today is
> my attempt at trying to satisfy the interests of a growing contributor
> community, and the wishes of the OpenStack community to provide
> clarity about the nature of various projects.
> 
> I am happy to work with you to help refine the OpenStack on-boarding
> materials, and find a ways to express the process in summary, and with
> links to supporting detail. I began hearing just this week, that
> community members liked the style of the Solum/Contributing page. If
> that's resonating with newcomers, then let's use what we are learning
> from it.

I will try to find some time to sit down and make some edits to 
GerritWorkflow, and then maybe we can work on integrating the Solum 
instructions?

> 
> Cheers,
> 
> Adrian
> 
> 
> 
> 
>> 
>>> Thanks,
>>> Adrian
>>>> /2 cents
>>>> -Ben