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