{"action":"created","issue":{"url":"https://api.github.com/repos/SnabbCo/snabbswitch/issues/702","labels_url":"https://api.github.com/repos/SnabbCo/snabbswitch/issues/702/labels{/name}","comments_url":"https://api.github.com/repos/SnabbCo/snabbswitch/issues/702/comments","events_url":"https://api.github.com/repos/SnabbCo/snabbswitch/issues/702/events","html_url":"https://github.com/SnabbCo/snabbswitch/issues/702","id":125929599,"number":702,"title":"Working with GitHub Issues","user":{"login":"eugeneia","id":4933566,"avatar_url":"https://avatars.githubusercontent.com/u/4933566?v=3","gravatar_id":"","url":"https://api.github.com/users/eugeneia","html_url":"https://github.com/eugeneia","followers_url":"https://api.github.com/users/eugeneia/followers","following_url":"https://api.github.com/users/eugeneia/following{/other_user}","gists_url":"https://api.github.com/users/eugeneia/gists{/gist_id}","starred_url":"https://api.github.com/users/eugeneia/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/eugeneia/subscriptions","organizations_url":"https://api.github.com/users/eugeneia/orgs","repos_url":"https://api.github.com/users/eugeneia/repos","events_url":"https://api.github.com/users/eugeneia/events{/privacy}","received_events_url":"https://api.github.com/users/eugeneia/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/SnabbCo/snabbswitch/labels/idea","name":"idea","color":"009800"}],"state":"open","locked":false,"assignee":{"login":"eugeneia","id":4933566,"avatar_url":"https://avatars.githubusercontent.com/u/4933566?v=3","gravatar_id":"","url":"https://api.github.com/users/eugeneia","html_url":"https://github.com/eugeneia","followers_url":"https://api.github.com/users/eugeneia/followers","following_url":"https://api.github.com/users/eugeneia/following{/other_user}","gists_url":"https://api.github.com/users/eugeneia/gists{/gist_id}","starred_url":"https://api.github.com/users/eugeneia/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/eugeneia/subscriptions","organizations_url":"https://api.github.com/users/eugeneia/orgs","repos_url":"https://api.github.com/users/eugeneia/repos","events_url":"https://api.github.com/users/eugeneia/events{/privacy}","received_events_url":"https://api.github.com/users/eugeneia/received_events","type":"User","site_admin":false},"milestone":null,"comments":2,"created_at":"2016-01-11T12:09:45Z","updated_at":"2016-01-17T11:14:22Z","closed_at":null,"body":"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!\r\n\r\n### Labels\r\n\r\nI 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.\r\n\r\n- `enhancement` - discussion about extending an existing feature\r\n- `idea` - discussion about a potential new feature\r\n- `bug` - an actionable re or developing port of a problem with Snabb Switch\r\n- `question`- a question about using or  developing Snabb Switch\r\n\r\n### Assignee\r\n\r\nThe “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.\r\n\r\n### Cross-referencing PRs and Issues\r\n\r\nIt 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:\r\n\r\n- an issue has related code or vice-versa\r\n- an issue can be closed (because code has been merged)\r\n- if an PR can be closed (because its issue has been resolved/rejected/superseded)\r\n- there is additional information worth reading up on\r\n\r\n### When to Close Issues\r\n\r\nCurrently, 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."},"comment":{"url":"https://api.github.com/repos/SnabbCo/snabbswitch/issues/comments/172314775","html_url":"https://github.com/SnabbCo/snabbswitch/issues/702#issuecomment-172314775","issue_url":"https://api.github.com/repos/SnabbCo/snabbswitch/issues/702","id":172314775,"user":{"login":"plajjan","id":841628,"avatar_url":"https://avatars.githubusercontent.com/u/841628?v=3","gravatar_id":"","url":"https://api.github.com/users/plajjan","html_url":"https://github.com/plajjan","followers_url":"https://api.github.com/users/plajjan/followers","following_url":"https://api.github.com/users/plajjan/following{/other_user}","gists_url":"https://api.github.com/users/plajjan/gists{/gist_id}","starred_url":"https://api.github.com/users/plajjan/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/plajjan/subscriptions","organizations_url":"https://api.github.com/users/plajjan/orgs","repos_url":"https://api.github.com/users/plajjan/repos","events_url":"https://api.github.com/users/plajjan/events{/privacy}","received_events_url":"https://api.github.com/users/plajjan/received_events","type":"User","site_admin":false},"created_at":"2016-01-17T11:14:22Z","updated_at":"2016-01-17T11:14:22Z","body":"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.\r\n\r\nSo if you want more people to help categorise issues you want to give them write but probably protect branches.\r\n\r\nThere'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.\r\n\r\nAs 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.\r\n\r\nQuestions 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.\r\n\r\nFor 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."}}