On 2014-02-12 15:34, Adrian Otto wrote:
On Feb 12, 2014, at 12:41 PM, Ben Nemec <openst...@nemebean.com>
wrote:
On 2014-02-12 13:48, Adrian Otto wrote:
On Feb 12, 2014, at 10:13 AM, Ben Nemec <openst...@nemebean.com>
wrote:
On 2014-02-12 09:51, Jesse Noller wrote:
On Feb 12, 2014, at 8:30 AM, Julie Pichon <jpic...@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
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
