Issue and pull request management details

Christoph Buchner edited this page Oct 28, 2015 · 15 revisions

Submitting pull requests

For specifics concerning pull request submission, see this wiki page.

Issue labeling

Incoming issues are labeled according to the existing and pretty complete label collection. Unfortunately, it's not possible to put labels on PRs, that's why it makes sense to have issues first. Labeling is used to categorize issues, and multiple labels can be used. Is the issue a bug or feature? In the core or an addon? Use OS- and IDE-specific labels, if an issue is restricted to a set of OSes or IDEs. Does the issue describe a small fix? etc. etc. Labels are also used to assign issues to certain sections via the section-xxx labels (except for iOS and documentation/examples, which already existed). Here's a detailed description of the labels' meanings:

  • bug/feature is self-explaining (dark red colors)

  • core/addon/example/documentation indicates the relevant section of oF for the issue (orange-yellow colors)

  • windows/linux/macOS/iOS/android/linuxarm/emscripten indicates the platform (blue-teal colors). Only used if the issue is limited to a subset of all platforms.

  • critical marks bugs which are much more important to fix than the average, e.g. crashes. (bright red)

  • "action labels" are in greenish colors:

  • bitesize indicates a small bug, easy to fix, probably doesn't take very long to close it. (good for beginners, hint, hint ;) )

  • prelim-analysis is set if a preliminary analysis of the issue has been made (e.g. showing proposed code that fixes it, a solution strategy, a good idea what causes a bug, a good reproduction example,...)

  • development-strategy has a larger scope (to avoid having too many different labels): All issues which need greater (core)developer attention, be it due to necessary strategical decisions, API changes, style questions,... in short, stuff that should be discussed more before the coding starts.

  • codeblocks/qtcreator/visual studio/xcode indicate IDE-specific issues. (purplish colors)

  • section-something labels designate that issues belong to certain sections. The respective section leaders are the primary point of contact for those.

  • project-generator labels all issues relevant for the OF project generator (black)

  • automation marks issues connected to OF automation which makes development easier - release packaging, automated testing, build/continuous integration servers, etc. While the project generator is also an automation mechanism, it is excluded here, and should be marked by its own label (dark grey)

  • apothecary marks issues concerning apothecary, our library upgrade and dependency handling script (light grey).


Where applicable, issues and PRs are also assigned to specific release targets with Milestones according to the Roadmap document and further considerations/common sense. Assigning an issue/PR to a release milestone does not mean that the issue can't be fixed/merged before that release, but that the release should not happen until all its assigned issues have been solved. With limited developer resources this often means, though, that development effort should typically concentrate on the issues assigned to the next milestone.

Once a milestone becomes the current/upcoming one, only critical and regression issues should be added to it. This will helps us keep releases at a reasonable size, and avoids feature creep.

Issue tracker website

It is possible to refine the issue list on github by clicking on the labels on the left hand side to show only issues having a certain set of labels. This is also reflected in the URL, so it's easy to automate if you want. Also, you can restrict the view to certain Milestones, that's handy if you need to prioritize bug treatment and concentrate on the next release. Milestones also give us an automatic assessment about how far along we are on our way towards a release.

I don't think it's possible to tailor Github notification with regard to labels - all admins of the repo get all notifications. If you need to summon someone to look at something, use the @<githubusername> syntax, and they'll get a notification. It will autocomplete for people with push access to the repo you're in, but will work with any GH username.


Initial treatment/labeling/assignment of newly incoming issues and labels is mainly done by the issue tracker leader. It is most appreciated, though, if new section leaders go through the list of existing issues, make sure they are labeled correctly (probably have to add a section-x label), and give their new bugs some love - make sure they're still relevant, get necessary information from the reporter, and start working on resolving them. There's a list of canned responses which may prove useful when dealing with bug reports.