meta: Issues and label system

[Kubuxu]

Issues in go-ipfs are mess, with almost 500 issues and problems with pipelineing we think that we can improve our and general workflow by organising issues and labels. This would make our and contributors work easier by highlighting areas of work that are in priority and allowing for faster navigation in issues and PRs.

Proposals from my side:

1. Prefixing issues with subsystem name (namesys, cli, test, sharness, etc.) or type (like this issue). Issue title is static for the most part, as is the subsystem or type of an issue.

2. Changes in label system. This is big part of this issue. As we have to go through all issues either way (to clean things up) we decided that changing labelling system and labelling all issues best we can.

   Currently we are looking at two styles of labels, docker and ethcore/parity.

   Parity system is not clear at first glance that is why I will try to explain it a bit:

   Labels in that system are divided into groups and differ by first letter. Majority of labels are under A (related to PRs) and F (related to actionable features) and would contain labels like: A0-needsrewiew, A1-inprogress, A2-signoffneeded, A3-justtoobig A4-looksgood, A5-insubstantial and the F group: F0-security, F1-bug, F1-build, F2-annoyance, F3-tests, F4-documentation and so on. As you can see the number is index and usually priority which can be seen in the P (Priority group): P0-dropeverything, P2-asap, P5-sometimesoon, P7-nicetohave and P9-somedaymaybe. This system characterises by very high information density as someone accustomed with it is able to use and assign issues using only two characters. It has a bit higher learning curve that very verbose docker's system but doesn't leave leave new users out.

   @gavofyork: It would be awesome if you could comment on how the label system is working for you in ethcore/parity

   I personally like the way parity does it as it has lower noise to information ratio and allows for assigning and skimming over labels with minimal thought required when you get used to it. For me it is important as the less thought spent on management equals more time and higher performance during coding.

3. Active and responsive assignment of labels, interlinking and closing issues. This is something we as developers need to work on. We decided recently to make go-ipfs issue tracker about go-ipfs only (previously it was about everything ipfs connected). If it can't be fixed by code or implemented right away then its place isn't go-ipfs tracker. We have many issue trackers open, you can see most of them here: https://github.com/ipfs/community/blob/master/contributing.md#reporting-issues

I would like to here everyone's opinions, no matter if you are collaborator, contributor, user or just bypasser, I love to here it, as perspectives and ideas of unconnected people make OpenSource work.

Bellow in a comment I will make list of labels I think of using.

cc @ipfs/go-ipfs-team @em-ly @RichardLitt

P.S. Sorry for the wall of text.

[Kubuxu]

Parity system labels adjusted for go-ipfs:

Actions:

Label	Colour	Use case
A0-pleasereview	#666666	ready for review
A1-inprogress	#e3cbcb	is still worked on
A2-signoffneeded	#f7c6c7	is missing sign-off / DCO
A2-gotissues	#f7c6c7	there are problems with PR that need to be resolved
A4-grumble	#fcdfc3	there are small changes needed
A5-mustntgrumble	#fef2c0	there are very small issues with PR that don't stop it from being merged
A6-looksgoodcantmerge	#dfecc0	PR is good but there are code unrelated problems (for example merge conflict)
A7-looksgood	#bfe5bf	reviewed and ready for merge
A8-onice	#c7def8	not ready for merge but can be reviewed
A9-insubstantial	#d4c5f9	extremely small or not connected to code PR

Features:

Label	Colour
F0-compatibility	#000000
F1-security	#b10d11
F2-bug	#eb3420
F2-build	#eb3420
F3-annoyance	#eb8420
F4-tests	#f3a603
F5-documentation	#fbca04
F6-refactor	#dbea04
F7-footprint	#009800
F7-optimisation	#009800
F8-enhancement	#006b75
F9-release	#207de5

Priority:

Label	Colour
P0-dropeverything	#32024c
P2-asap	#470c68
P5-sometimesoon	#673980
P7-nicetohave	#856d92
P9-somedaymaybe	#d2d1d3

Misc:

Label	Colour
B0-unconfirmed	#dddddd
Z-duplicate	#ffffff
Z-invalid	#ffffff
Z-question	#f8f8f8
Z-wontfix	#ffffff
D0-easy	?
D1-moderate	?
D2-hard	?

We don't need Help Wanted as when we clean up issues everything should be open for help, and priority, difficulty and feature type will guide contributors more cleanly. 'Help Wanted' is our way of navigating in current mess.

[RichardLitt]

Thanks, @Kubuxu.

Prefixing issues with subsystem name (namesys, cli, test, sharness, etc.) or type (like this issue). Issue title is static for the most part, as is the subsystem or type of an issue.

This sounds good to me, but I would clarify which you want - subsytem name, or type? We can also rename issue titles as needed to make it easier.

I am a fan of parity's labels, and I think those would work well for us. I also think that an active labeller label party sounds good; let's go through and label all the things.

[Kubuxu]

Subsystem name if it fits, if not then type. There is no subsystem for meta for example. We could make it subsystem/type but I think most types that would connect with subsystems will be covered by labels.

[Kubuxu]

In other issue I mentioned three things that could help us manage the issues:

1. LGTM bot for our Code Review process that would automagically add RFM (A7-looksgood) label on LGTM comments from given set of people.
2. 'in progress' bot that would mark issue 'in progress' (A1-inprogress) when issue is linked by Resolves keyword with PR. If PR is closed without merge the label should be removed.
3. Blocked by graph. Crawler that would look through issues and PRs in the organization to find the most substantial blockers. If we start using those keywords, it would help greatly.

[whyrusleeping]

I like this, i'm all for moving to a better labeling system. We can likely drop the difficulty tags, I personally dont find them that useful and always end up marking things as easy or moderate. Tasks can be more or less difficult depending on the person looking at them.

Setting up a bot to automate a lot of this would be fantastic. Lets do it.

As for subsystem, what i've seen in other projects is to prefix is with the folder (relative the repo) the issue primarily deals with (as opposed to a broader subsystem). In some cases though the broader subsystem prefixing might make more sense (in cases where the issue touches many different areas of the codebase)

[Kubuxu]

Good insight, as go-ipfs repo subsystems are managed in directories nicely it makes a lot of sense.

[RichardLitt]

We can likely drop the difficulty tags, I personally dont find them that useful and always end up marking things as easy or moderate. Tasks can be more or less difficult depending on the person looking at them.

I'm not sure - they're not for you, they're for people who may be interested in hacking on IPFS. If you want, only use them with the 'help wanted' label. That's how it's being used elsewhere.

Is there anything else we're waiting on before this is a go, @Kubuxu?

[Kubuxu]

I don't think so. For it to be go we need just set labels (I can do that) and start going through past issues.

My comment regarding difficulty: the easy should be really the easiest things, then medium and hard will get uses too.

[RichardLitt]

You can use github-labels to set labels programmatically.

[Kubuxu]

That is what I used to export them from ethcore/parity, we should first rename labels that will stay in. Should I do it?

[RichardLitt]

Sounds good to me. I'm not sure all of the labels from ethcore make sense -- I have no idea what mustntgrumble means, for instance.

[Kubuxu]

It is for case when PR is generally OK, but there is some small issues or feature missing but it can be resolved later. It could be removed but let's see if we will be using it.

[Kubuxu]

Before we start with this, I think we should create document explaining every label and its intended use, sounds good?

[RichardLitt]

Sounds good to me. Want me to do it? We used to have one of these, I can dig it up.

[Kubuxu]

I've done it for the A group. If it looks enough for then doing same for other groups would be great, if it is too laconic then it would be great if you could expand them. Thanks.

[RichardLitt]

I don't think the other groups need them - they are very clear as they are. I struggled to explain them more.

One thing:

We don't need Help Wanted as when we clean up issues everything should be open for help, and priority, difficulty and feature type will guide contributors more cleanly. 'Help Wanted' is our way of navigating in current mess.

I disagree with this. "Help Wanted" is what we're using for newcomers to the project. We should assign 3-5 issues with this label, with varying difficulty levels, for people who want to help out. This is not for us - it is for them. We are using this across the GitHub organization, and in the up-for-grabs community. For more on this, see this issue. For this reason, we should also keep D0-easy as difficulty: easy. There is a definite benefit for having things labelled this way, I think.

[Kubuxu]

Problem with assigning only 3-5 issues with "Help Wanted" is that different issues fit different people. We currently have over 50 "Help Wanted" issues. Clear priority and difficulty system, IMO, will work better than "Help Wanted" which is assigned quite arbitrarily or "there isn't anyone working on it right now".

D0-easy vs difficulty: easy: org wide search will be very rarely used by new contributors and in case of up-for-grabs we can define separate search terms for go-ipfs and rest of ipfs

(also the up-for-grabs of IPFS is currently broken).

[RichardLitt]

I think we should cut down on "Help Wanted" issues. Those should be specifically for things which are good for onboarding new users. We can change the label -- just checked on up-for-grabs -- to something else, but I like the idea of having a very clear onboarding process for people, that isn't just "choose an issue with an appropriate priority and difficulty system. Help Wanted issues should ideally be curated; a lot of effort should be put into them to make them easy to do for newcomers.

I am not sure a separate search term is the best idea, but I can't back this up with something other than a gut feeling. We currently have a "search for help wanted issues" link in a few places (at least on community), and I would like that to be for the entire org, not just org minus go-ipfs.

Will fix up for grabs.

[RichardLitt]

I see a lot of PRs like this https://github.com/ipfs/go-ipfs/pull/2941, with pretty much just hash updates. Should we label those appropriately? What about stuff like 'gx'? Should that remain a label?

Are there any labels that we commonly use that are useful?

[Kubuxu]

Not really, we can note this in the Title and it is very clear from both commits and code that there was deps update. It isn't important from management and priorities perspective that it was deps update.

[RichardLitt]

Would be good to keep 'waiting on author' and 'needs signoff', 'needs review', and 'rfm'. Right?

@Kubuxu How can I help, at the moment?

[Kubuxu]

We need to rename existing labels that should stay with new naming scheme. Sounds good? If you have any questions, ask.

[RichardLitt]

@em-ly @whyrusleeping Are you ready for this to happen? Once we rename, we should add in missing labels ASAP.

[RichardLitt]

Should we automatically label issues, too? For instance:

Type (bug, feature, meta, test failure, question): bug

Using the go-ipfs template, this could automatically be labelled bug, fairly easily I believe.

[ghost]

I like how the absence of any labels on an issue signifies "nobody has had a look at this yet" -- but on the other hand we could have another label (inbox) for exactly that purpose :)