Working with GitHub Issues

[eugeneia]

I want to start maintaining the “Issues” tab a bit more actively. I looked a bit about how we use labels/assignment/cross-referencing and want to propose some conventions. Feedback is welcome!

Labels

I would like that we use labels more to organize issues. I just went over all open issues and labeled them to get a feel for this. Labels are like tags (not like categories) and you can put multiple labels on an issue. Right now we use four different labels and below is a legend of what I think they should mean, intended to help you pick the right label for your issue.

• enhancement - discussion about extending an existing feature
• idea - discussion about a potential new feature
• bug - an actionable re or developing port of a problem with Snabb Switch
• question- a question about using or developing Snabb Switch

Assignee

The “Assignee” setting is currently not used very much, but I think its useful to know who to bug about an issue. Generally speaking, assign yourself if you intend to work on the issue. (I am not sure how the permissions work here, who can assign people to issues? Everybody? Just repository admins?) I think the most important advantage of having an assignee is to prevent duplicate efforts. I propose: Don't work on an issue before talking to the assignee (if one exists) or you risk duplicating work.

Cross-referencing PRs and Issues

It is very valuable to have cross-referenced issues / PRs because they give actionable information about an issues / PRs status. You can do that by mentioning a PR or Issue in the discussion of another PR or Issue (e.g.: “See #XXX because Y”) and then the mentioned PR's or Issue's discussion will automatically get a “back reference“. Please try to cross-reference as much as possible as it really helps to to tell if:

• an issue has related code or vice-versa
• an issue can be closed (because code has been merged)
• if an PR can be closed (because its issue has been resolved/rejected/superseded)
• there is additional information worth reading up on

When to Close Issues

Currently, I only ever close issues that are clearly “resolved” by means of merged PRs or otherwise. I find it very hard to tell if an issue can be closed. Some issues are very old and haven't seen any action in a while but are not resolved either. Especially “enhancement” and “idea” tagged PRs tend to just sit there, being not implemented nor rejected. Luckily it is possible to reopen Issues. From time to time I will dare to close an issue without being 100% sure its the right thing to do. In that case I depend on the involved people to complain abd reopen the Issue.

[lukego]

Great initiative!

Generally I believe that Github doesn't let people self-assign issues and it is a bit locked down. I am not an expert on Github permissions (have previously set them conservatively mostly to avoid e.g. accidental force pushes to important branches like master). Let me know if there is something I should check or change.

"Open" and "Closed" are interesting. I see the meaning for bugs: open means action needed to investigate/resolve. Likewise with PRs: open means the creator wants the commits to be pulled. Questions perhaps too: is the creator satisfied that they received an answer. How about ideas though? Do we just leave those open? Or close e.g. when somebody creates a new one that restates the idea?

Could also be nice to keep track of which issues could be fixed in some direct way (e.g. a reproducible bug) and ones that are causing problems for users (e.g. the IOMMU setting issue that has been haunting us for much too long now but requires some detective work to understand and fix/document.)

[plajjan]

GitHub has admin/read/write access. Admin allows everything. Write is allowed to push to the repo while read obviously only allows reading. From an issue management perspective you need write to be able to add labels, set milestone and assignee. You can use protected branches to prevent people with write access from being able to push directly to a branch, so everyone has to go via PRs.

So if you want more people to help categorise issues you want to give them write but probably protect branches.

There's functionality so that you can write "Fixes #1234" in a commit and it will automatically close that issue when the commit mentioning it has landed on your base branch. "master" is the default base branch but you can change this in the repo settings as well. Since you use a next branch for everything maybe it makes sense to close the issues when it has landed on that one.

As for easy to fix vs hard you can just add labels for that. For example, a low-hanging-fruit label can help newcomers looking to contribute find simple things to fix.

Questions aren't really issues in the same way. A "normal" issue means there is some problem with the code but a question could be just to help a user get something working and doesn't necessarily indicate an issue with the code.

For ideas, which are more of high level concepts, I like to "branch out" the issue into more low level actionable items once it has been discussed and potential solutions have been reached. Once those low level issues are fixed, by committed code, then high level idea can be closed, or if you prefer you can close it as soon as the low level issues have been created.

[lukego]

@eugeneia we could also define some interesting categories of Issue as Github search terms e.g. encoded into a link like open bugs or open ideas. These would be actionable in different ways e.g. it could be a priority to close all of the open bugs but harmless to leave the ideas open unless/until they are adopted or rejected.