Proposal for issue tracking

[Christian Helmuth]

Hello everyone,

we're now walking the open path. Therefore, I want to discuss my ideas
about the future issue-tracking process of Genode here on the list.


The challenge

The current "process" of handling issues is rather pragmatic and
little transparent for the community. Most issues are reported and
discussed on this mailing list. Hence, reports are mostly unstructured
and difficult to track. At Genode Labs, we maintain a private tracker
for our projects partially of interest for the Genode community. So,
the first step (as Norman already wrote) is to migrate these issues
into a publicly accessible tracker.

Furthermore, issues have some quirks to keep in mind when deciding
upon on a tracking process. First, apparently resolved issues may rise
from grave and it's precious to have their history at hand to fight
them back. Also, the resolution of closed issues should be accessible
in the code repository to know when and how it works. Sometimes it's
also good to find out who fixed the issue and, thus, have a contact
for further questions. Finally, a well maintained issue database
reflects the current stage and activity of the project, assists
contributors to get started, and reflects which missing features are
already in the back of our minds.

We decided to go for a public Git-based repository for Genode sources
and, so, it is natural to go for an open collaboration model. Two
widely used models are the "Fork + pull-request model" and patch-based
integration. IMO both should be supported.

In the following, I will now and then evaluate features available from
GitHub to our requirements. We did not finally choose GitHub but I
must admit I'm a strong proponent of this platform.


Reporting an issue

We definitely need a simple guide on "How to report an issue" to avoid
the tedious question-and-answer game. My proposal is:

1. Summarize important information of your issue in the _title_.
2. Start the _body_ with steps to reproduce it. Name the affected
   version/commit.
3. Sketch the expected behaviour.
4. Detail what happened instead.


The life cycle of an issue

After the issue was reported it will undergo a life cycle until it's
eventually closed. Each life stage depends on the issue type and the
steps taken to resolve it. The important issue types I identified are
_bug_, _feature_, and _documentation_. The issue type should be marked
in the tracker and may be used for filtering/sorting.

If someone works on a reported issue, he may want to submit a fix as
_patch_ or as _pull_ request. Pull request should come from a
persistent topic branch in a fork of the main repository. So, the
issue and its history can be tracked in the future. The fact of a
submitted fix shall also be marked in the tracker. Moreover,
discussions upon an issue should be attached to the issue in the
tracker.

Eventually, a decision on the issue will be reached, which can be that
a _fix_ was accepted or incorporated, the issue was identified as a
_duplicate_ of an older issue filed, or the issue was _rejected_ by
some cause. If the issue revives it may be reopened and the cycle
starts over.

Some optional features I did not investigate further, but that may
become useful are: assignment to team members, tagging an affected
release version, and an urgency marker.


Does it work every day with GitHub?

To get hands-on with the issue tracking I added a playground
repository to my GitHub account. The associated issue tracker can be
found under

  https://github.com/chelmuth/playground/issues

I added _tags_ to mark all the information mentioned before.

The integration of Git and the GitHub platform is quite good. Issues
can be referenced in discussion threads of other issues as well as in
commit messages via '#<issue number>', e.g., #1. Issues also have
their own URL, e.g.,

  https://github.com/chelmuth/playground/issues/4

Issues even can be closed from commit messages. The committer just
adds a recognizable text, e.g., 'Fixes #3'. For more information have
a look at

  https://github.com/blog/831-issues-2-0-the-next-generation

Another interesting feature is the reference of other developers on
GitHub via '@<username>', e.g. @chelmuth. Hence, the involvement of
potential contributors into the discussion is straightforward.

Finally, GitHub provides (on the web and via the 'hub' tool [1])
excellent integration of the fork+pull collaboration model. This
feature is described in detail at

  http://help.github.com/send-pull-requests/

The idea of handling pull requests like issues including a discussion
thread is great.


I'm looking forward to your feedback.

[1] http://defunkt.io/hub/

Kind regards
-- 
Christian Helmuth
Genode Labs

http://www.genode-labs.com/ · http://genode.org/ · /ˈdʒiː.nəʊd/

Genode Labs GmbH · Amtsgericht Dresden · HRB 28424 · Sitz Dresden
Geschäftsführer: Dr.-Ing. Norman Feske, Christian Helmuth