Proposal: options for issue prioritisation

[vitorgalvao]

I had been thinking for the past few weeks about how inadequate github issues can be for us, and #17323 is validation of that. It’s not the first time (and I’m including myself) a maintainer can’t recall if something is implemented, or is under the impression it is because it has been talked about so much.

I have also been thinking about how to solve it, but haven’t really settled on a great solution. It is clear, however, the goal of the system should be clarity (which is what’s lacking in the issues system), namely clarity in prioritisation (doesn’t necessarily mean features nave to be implemented in that order, but it should rate them by importance), which also brings with it clarity in what needs to be tackled.

This could also encourage more users to contribute to the core, if they have a place they can reliably go to to see what needs to be done.

Some possibilities:

Master issue

• Pro: Uses the familiar issues system.
• Con: As more issues are opened and closed, it may become harder to keep track of where it is, and possible contributors may not even see it.
• Con: Can become messy when (almost inevitably) there is discussion it the issue itself.

Document on the repo

• Pro: Easy to keep track of where it is.
• Pro: Every addition/removal is clearly visible to maintainers/repo watchers (as long as it’s made as a PR).
• Con: Can be hard to find if you don’t know it exists.

External system (e.g. Trello)

• Pro: Great at prioritisation and tracking progress.
• Con: Requires use of an external website/service.

---

My favourite option is the document in the repo. Its con can be mitigated in two ways: the second pro, since it’ll lend it visibility, and being featured in CONTRIBUTING, in the section about contributing to the core (this would also apply to the first con of the master issue option).

[adidalal]

My ideal preference would be a separate bug-tracking system, but that's not a great solution for external contributors - I've been to more than one OSS project where another place for Issues were used, and I simply didn't want to register to submit a bug, etc. - In short, it's a very high barrier to entry, and not something I would deem appropriate for HBC. (Excellent return on effort, good transparency, but super high barrier for new contributors)

A document on the repo is actually moving in the wrong direction, I feel - instead of atomic, separable issues, you get links out to other things, for no real reason other than to prioritize. Keeping this list up to date becomes more work, and seems a bit unwieldy. (Low return on effort, and needs to be done every time)

While not perfect, I propose a revamp of the labels and (ab)using the Milestone system. You can filter by both label and Milestone, and since it's on GitHub, theres no particularly large learning curve. (Medium return on effort, minimal barrier to entry)

There's a lot of literature on the subject, and while I have my own thoughts on the matter and a proposed system I can expand upon if there's interest, some links to get the discussion rolling.

http://radek.io/2015/08/24/github-issues/
https://mediocre.com/forum/topics/how-we-use-labels-on-github-issues-at-mediocre-laboratories
http://www.ianbicking.org/blog/2014/03/use-github-issues-to-organize-a-project.html

tl;dr: Let's use issues but fix our labelling system to make things easier to track (priority-wise) and friendlier for contributors.

[vitorgalvao]

but that's a great solution for external contributors

Do you mean “not a great solution”?

My take on milestones:

• Pro: Shown directly on the issues relevant to them.
• Con: It somewhat discourages outside contributions (looks like “the team is already working on this”).
• Con: They are hidden in the issues section, which makes it hard to remember they even exist.

The second con is mitigated by the pro, and the first might just be my impression, so it still comes out positive.

I feel relying on people (both contributors and maintainers) to filter issues is likely a losing proposition. Usually issues are seen in a light of “let’s see what’s there” instead of “let’s look for something related to this”. Labels help to visually distinguish stuff when looking at everything, but filtering is (I feel) less used.

In all, I agree with all your criticism, and that revamping labels (we need fewer of them; some like bug are useful, while others like enhancement are rarely so) would be good, as might be using milestones. I would also like to know about your proposed system.

[adidalal]

Yes, meant not a great solution. Updated post to avoid confusion.

---

Visibility of issues/milestones is, I feel, a direct result of our documentation - If CONTRIBUTING is short but links out appropriately to URLS (you can link directly to labels/milestones), that con is mitigated. (i.e. New to contributing to HBC, check out this list of issues; want to work on the core, click here; want to help with documentation/design/adding new casks, see open ___ issues, etc - not an ideal solution by any means but just a thought of how that could work).

Will take a look at the currently used labels and what they are used for (from MAINTAINING), and write up another post as I get the time.

[jawshooah]

There's also ZenHub, which is free for open-source projects and provides all of the functionality discussed here (prioritization, scheduling, milestones) while integrating directly into the GitHub Issues view.

[adidalal]

There's also moving the project to GitLab (a response to the Dear GitHub letter) - which is a much more involved discussion and likely overkill for this scenario alone. Food for thought, though.

[vitorgalvao]

@jawshooah Oh, right, I had seen that before. And it even has a section that looks like Trello.

@adidalal Moving away from github is indeed overkill, and would likely do more harm than good.

• Github acknowledged the letter and has shown good will towards solving those issues.
• Gitlab is “dog slow”, and they acknowledge that.
• Github has familiarity over Gitlab and attracts maintainers that otherwise wouldn’t contribute.

[adidalal]

RE: ZenHub, I use Safari because I prioritize battery life, so that wouldn't work for me, but I think the pros/cons are the same as using Trello, etc.

[jawshooah]

@adidalal There's definitely demand for a Safari ZenHub extension, but the owners haven't shown much interest so far 😞

[joshka]

You could also consider waffle.io or huboard.com. I have not used either, but both are free / free for open source projects. As a fairly new cask contributor, seeing issues on github rather than another secondary site is a plus for me.

[adidalal]

@joshka I'm wary of adding another layer of indirection - It may work the best for large projects, but I don't see us as needing so many features. Still haven't found time to write out a revised tag chart but will at some point.

Ionic has a cool issue form, but again, seems like overkill for us: http://ionicframework.com/submit-issue/

[adidalal]

Been long overdue, but preliminary thoughts:

Kill:
cask
bug
chief bug (maybe rename to critical?)
duplicate
enhancement
future
roadmap

Add new labels for difficulty:
Beginner
Intermediate
Bigger project

Rename:
ready to implement -> help wanted?

I really like the outline at http://radek.io/2015/08/24/github-issues/

The relevant argument against prioritizing:

While these two are probably the most common ways of categorising software tickets, I’m not sure how useful they are for open source projects. For companies, these can be used to prioritise employee’s time and make sure problems critical for the business are tackled first.

With open source projects though, people just work on what they want to work on. Different people will see these very differently based on how they use the app and what’s important to them.

Also, marking issues low priority and trivial severity isn’t very encouraging for people to start working on them. These are exactly the type of issues you want newcomers to be tackling first, so they get up to speed with the project and marking the work inconsequential is wrong. The goal of a trivial, low priority issue is to get a new contributor onboard. That’s bloody high priority to me…

---

However, I understand having a roadmap is nice. I propose we use milestones:

Stuff we are doing right now: this is the “main” milestone. We give it a name (like Alpha 2 or Strawberry Rhubarb Pie) and we write down what we are trying to accomplish with the milestone. We create a new milestone when we are ready for the next iteration.

Stuff we’ll probably do soon: this is a standing “Next Tasks” milestone. We never change or rename this milestone.

Stuff we probably won’t do soon: this is a standing “Blue Sky” milestone. We refer to these tickets and sometimes look through them, but they are easy to ignore, somewhat intentionally ignored.

What aren’t we sure about?: issues with no milestone.

We use a permanent “Next Tasks” milestone (as opposed to renaming it to “Alpha 3” or actual-next-iteration milestone) because we don’t want to presume or default to including something in the real next iteration. When we’re ready to start planning the next iteration we’ll create a new milestone, and only deliberately move things into that milestone.

(from http://www.ianbicking.org/blog/2014/03/use-github-issues-to-organize-a-project.html)

[vitorgalvao]

To be honest, I disagree with most of that proposal.

chief bug (maybe rename to critical?)

We need to keep that one. The label doesn’t mean it’s severe, it means people keep asking about it. When we see a request over and over, that’s the clue we can use to track it down fast.

future

As it says, that one is to be used sparingly. It’s a nice one to have to track big changes.

Those two are very useful and used almost never. That makes them good candidates to exist, as they truly help sorting.

cask

I’d go the opposite direction. Lets remove core instead. Most issues that linger are related to the core, not casks (those are usually handled quickly), so we need cask to quickly find and fix those. I could see cask request being removed, though.

bug
enhancement

Then how do we distinguish something to be added from something that isn’t working? I can’t see a reason in any project that actually has code to remove bug.

Add new labels for difficulty

I strongly believe those will accomplish nothing. Not only are they highly subjective, if you’re intermediate or higher you can identify the difficulty of something as it compares to your skill, and already need to be familiar with the project anyway. The beginner one might be useful.

ready to implement -> help wanted?

Again, you’re misinterpreting the label. That doesn’t mean we need help to make the feature happen, it means all the details are in place and everything is decided. Only the doing part remains. It’s as useful to us core maintainers as to outsiders.

Stuff we are doing right now (…) Stuff we’ll probably do soon

Those don’t exist. We’re not a company, but volunteers, and as such what we can do and when highly fluctuates. There is nothing we can accurately categorise as “probably doing soon”, and “what we’re doing now” discourages outsiders from helping.

Most people don’t contribute to the core, and those who do, do so to scratch their itch. What we really need help with (and have a fighting chance of getting) are long/medium easy tasks, like adding name to all fonts, fixing wrong fonts, adding appcasts, writing documentation and the occasional tweak to the core or fix/adding of a cask.

[adidalal]

I'm good with adding a beginner label. (and adding the corresponding link to CONTRIBUTING)

I'd also like to keep core as most people don't actually filter, and that's a useful label (along with documentation). I see how keeping cask helps in your case, though.

Impartial on cask request - we could either rename the issue or keep the label, and I guess the label helps filtering, so why not.

I end up thinking enhancement is useless, but we should keep bug. ie, everything's an enhancement unless it's a bug.

(Trying to minimize labelling for our most common case - a new/update cask PR that needs user reply - one label should suffice)

[vitorgalvao]

Github replied to the letter.
HN discussion.

[vitorgalvao]

We reached no consensus and I feel this is less pressing now than it was at the time it was written. Closing.