[lucy-dev] "contributing" and "todo" resources

[Marvin Humphrey <ma...@rectangular.com>]

On Thu, Feb 7, 2013 at 9:29 PM, Logan Bell <lo...@gmail.com> wrote:
> The one thing that you mentioned below is the sad state the STATUS
> file, and to be perfectly honest I have actually never looked at the
> file until probably now. I'm wondering if there is a better way to
> keep todos organized? Further it looks like the STATUS file has become
> out of sync with the JIRA issue tracker.

Let's break this down.

The main problem we want to solve here is answering the question, "How do I
contribute to Lucy?"

I propose that we respond by providing the following URL:

    lucy.apache.org/contributing

On loading that URL, the user would be redirected to the CONTRIBUTING document
which lives in the root dir of the main Lucy source tree:

    https://git-wip-us.apache.org/repos/asf?p=lucy.git;a=blob;f=CONTRIBUTING;hb=refs/heads/master

In the past, the redirect might have led to a HowToContribute wiki page.

In any case, conceptually, the "contributing" resource would be a static
document describing how to contribute to Lucy.

Next, we need a "todo" resource:

    lucy.apache.org/todo

It should provide a whitelist of TODO items which have garnered consensus.

Right now, the STATUS document theoretically fills that role, but it's not
being updated consistently enough.  Maintaining a STATUS document works for
the Apache HTTPD community, but it doesn't seem to have caught on here.  With
some additional effort, we could probably make STATUS work for us -- but I'm
not averse to experimenting with an issue tracker report instead.

Lastly, we should try to maintain a pipeline of issues which are truly entry
level work, and which are small enough to be completed in a reasonable amount
of time.  Prepping such issues requires energy from core developers, and
although there's no problem mustering that energy at the moment, we should
anticipate that won't always be the case and be prepared to fall back
gracefully.

I'd suggest using JIRA's "labels" feature to tag issues:

*   "todo" for items which have consensus
*   "easy" for entry-level work

That way we can make lucy.apache.org/todo redirect to a JIRA search for the
"todo" label.

    https://issues.apache.org/jira/issues/?jql=project%20%3D%20LUCY%20AND%20status%20NOT%20IN%20%28Closed%2C%20Resolved%29%20AND%20labels%20IN%20%28todo%29%20ORDER%20BY%20created%20DESC

Issues discussed on the Lucy dev list for which consensus had been achieved --
including lazy consensus of course -- could receive the "todo" label.
Additionally, to bias us towards action, the "todo" label could be applied to
minor issues by anybody with a JIRA account -- generating an email
notification to issues@lucy.a.o -- and if nobody objects, the issue gets
whitelisted via lazy consensus.  (Lucy PMC members should be subscribed to the
issues list.)

> Also, just looking over our issue tracker it would appear Lucy has no
> todos: https://issues.apache.org/jira/browse/LUCY. I guess more
> correctly "popular todos", which according to this page need to be
> voted on. I'd be willing to generate a list of open/pending todos and
> perhaps get consensus on which ones should appear in the popular
> portion of our issue tracker for would be developers to glean over.

The venue where we set our agenda is the dev list, not the issue tracker.  Any
individual can open an issue at any time without building consensus, but
making a proposal on the dev list gives everyone interested in Lucy's
evolution a chance to weigh in.  And with regards to voting, an issue can be
both popular and contentious, in which case it really needs to be discussed on
the dev list before somebody puts a lot of work into it.

It would be unfortunate if a newcomer were to pick up an issue and prepare a
patch -- especially a large one -- only to find out after the fact that there
either the feature itself or the approach was a source of contention.  We'd
end up with unhappy contributors, an inconsistent code base, or both.

We can do better.

Marvin Humphrey