GH Issues Pilot - Week 1 Retrospective Thread

[R.A. Porter]

We're coming to the end of the first week of the pilot and I think things are going incredibly well, all things considered. We're still feeling our way around workflows and processes and will be for quite some time, but in terms of issue generation and basics, we're way ahead of where I expected to be by now. I thought we'd still be bouncing back and forth, fighting against the change, and fighting with the tools.

I want to give a broad shout-out to everyone who has created or worked on an Issue/Pull Request this week. We're all of us getting over some bad habits that have developed with ticket writing and I've been really impressed with everyone's openness and willingness to take constructive feedback to improve their issues. I've also noticed how that feedback is already being internalized; the next issue filed from an engineer who's had to go back to satisfy some criticisms is always 100% better from the get-go. These are bad habits that we've let settle in for a long time, so it's going to take a lot of effort and support to break ourselves of them. I'm glad that the community is working together effectively and not being defensive or resistant.

And that's true of the switchover itself, too. I haven't heard any grumbling about doing things differently being a bad thing and that's good. We're all hoping this change will be a good thing in the long-run. Of course people might not be grumbling to me so I can't say for sure everyone is happy. That's what this thread is for.

I also want to give one more shout-out to the people who've been working on the repository metadata this week. We've gone from a pretty useless, single Issue template to a set of Issue templates that I think will be a really good jumping off point for us to refine that side of the process. We're looking to do the same on the PR side of the process, to help generate better pull requests that are more tailored to our changes and to potentially automate some of our more basic workflow tasks.

Anyway, thanks to everyone for working hard and together to make this a productive week one of the pilot. Now, I open the thread up to discussion, complaints, suggestions, etc.

-Richard

[Ethan Manns]

I only have minor issues with the pilot so far. I'm not a fan of how issues and PRs share the same numbering system. I think it's confusing and I fail to see any benefit for doing it that way (except for linking via #<number>, which I think could have been solved in a variety of other ways).

It appears that Github issues doesn't offer and kind of automatic linking to the PRs? It appears that we still have to manually link the Issue to the PR? I'm hoping I'm wrong and somebody can correct me.

-Ethan Manns

[Emily Berk]

Here are some of my thoughts so far:

• I couldn't find a good way to link (and add the reciprocal link to) tickets (e.g. "related to", "spawned from", "blocked by" links in Jira). Furthermore, the way to link a PR with its issue is to include the issue number in the PR description, which makes a link to the PR show up in the comments of the issue. How do we differentiate between PRs that fix the issue and PRs that just reference the issue?
  
• Multiple tickets per issue is not as straightforward as Jira.
• It there a way to specify the fix version with some defined set of unreleased/released versions instead of just text that isn't enforced? Is there a way to require that the fix version is specified when an issue is closed? Is there a way to view fixes by version? Can milestones be used to accomplish these goals? Can any user set milestones? Does setting the milestone on a PR have a different effect than setting the milestone on an issue?
• It's not clear who is assigned to issues. How do we differentiate between an issue that is actively being worked and issues that are just reported?
  

These are not deal-breakers but rather features that I was accustomed to in Jira. I think adding some issue/PR documentation would address these concerns.

[vinama...@gmail.com]

It's not clear who is assigned to issues. How do we differentiate between an issue that is actively being worked and issues that are just reported?

This is one of my big frustrations too but unfortunately I think assignees at least in the Github sense can only be set by committers. This makes it hard for people to pick up issues because there's the risk that someone is already working it (in most cases the reporter). 

I wonder if there's some workaround we can use like commenting on the issue since Github's permissions make this difficult.  

[R.A. Porter]

The sharing of numbers is a GH thing; we can't control that. I think in the long run we will be able to adapt to take advantage of it, as we'll be able to easily reference other tickets and other issues in-line but I don't disagree that separate numbers might be more straightforward.

References between issues/PRs do show up, but there's no hard-linking between them. All references appear in the event list beneath the description; there's no stable place to see them right now and no way to distinguish between a "this is related to" and "this is work specific for" type reference. If a PR indicates that it 

Fixes:XXXX

then it will include "...referenced a pull request that will close this issue..." in the link message.

GH issues are less structured than Jira (which, personally, I like a lot) and don't enforce the sort of linkages between issues and PRs that Jira does.

As I mentioned above, the "Fixes:" notation will tie the PR more tightly to the Issue, but GH has an expectation of one Fixes PR per ticket so there are drawbacks there if you want to attach multiple PRs for a single issue.

We haven't done very much at all with GH Projects, but I suspect as these become more fleshed out that we'll have projects associated with a specific release version. We can also use milestones more, but that's another thing that only committers can set, unfortunately.

I think the suggestion that we use comments for "I'm picking up this issue now" is probably our best bet. A committer will be able to assign the issue pretty quickly after seeing that.

-Richard