Using GitHub milestones for tracking current and future work


#1

I’ve been speaking with @chessbyte the last few days about how to give better transparency and understanding into the current lines of work, and one of the things we decided upon was leveraging GitHub milestones. We already use GitHub issues for management of issues, and so it is a logical extension to use GitHub milestones.

I’ve gone back and moved all the old merged PRs into “old” sprint buckets. Moving forward, @chessbyte, @xav and other leads will populate the issues and bugs that must make it into next sprint. From there we can see how far along the sprint is coming, and what features are already in or on their way to getting into future sprints.

For people with push access, you will need to put any merged PRs into the current milestone as part of the merge process. Eventually I will write something to teach the bot to do it automatically, but for now you will have to do it manually. /cc @chessbyte, @dclarizio, @gmccullough, @rpo, @blomquisg, @kbrock, @jrafanie


#2

Can I suggest that we also consider, purely as a hedge against having
issues with github in the future, that we figure out how to get all this
metadata out of Docker and use it in an alternative tool when adopting
milestones (and issues and pull requests)? I think it’s important to
think about what the alternatives are, or exit strategy is, when
adopting github specific features. @johnmark, what do you think?


#3

@dneary When you say Docker, I assume you meant GitHub? Is your comment to hedge about milestones specifically or GitHub Issues in general? If GitHub issues in general, then please open a separate topic.


#4

Github has a very complete API: https://developer.github.com/v3/


#5

@fryguy (to be read as a chant): Teach the bot…Teach the bot…Teach the bot


#6

Also see https://github.com/peter-murach/github . How do you think I got 400 PRs in their respective buckets? :wink:


#7

Yes, I meant GitHub. But isn’t everything Docker these days? :wink:

Dave.


#8

This reminds me of http://keepachangelog.com/ (/via the changelog podcast)

In particular, I liked their discussion on release notes. Interesting to read about the 2 types of git tags, and how they are suggesting to use them for release notes.

These topics all seem related. Grouping issues together into a changelog, release, or work buckets.


#9

Are milestones like putting a label on a PR so we can all know where this code will get merged?

Would be nice to see a “label” with the branch that will get the change. Whether it is 5.3.z or 5.2.z. That would clearly set expectations.

Not sure if it is a label or a milestone. Not sure if we could auto assign the label bz based upon the bz.

@blomquisg I’m impressed with github api. There is a good summary of agile workflow that mentions a few tools like sprint.ly.


#10

@kbrock, re: version numbers as github labels. We should avoid using downstream version numbers as github tags. But, we could could use upstream release names.

Of course, we do include bugzilla numbers in PRs, so … what do I know?


#11

@kbrock, re: changelogs, release notes, and annotated tags. Interesting idea! It would be nice to have the change log entered into the annotated tag, so git show tag_version would list out the change log. Then, CHANGELOG.md could be updated from that tag’s annotation.

Sounds like more work for a bot :wink:


#12

We don’t have to mention downstream versions but ‘labelling’ a PR in upstream as a “backport candidate” or something could help whoever is evaluating backporting fixes to either upstream or downstream releases to make sure we don’t miss something. If a developer is fairly familiar with the code area, they should be able to evaluate what’s a “backport candidate” and it’s easy enough to unlabel if it’s not worthy. Of course downstream has a different criteria for what’s backportable than upstream releases but labelling potential candidates could help filter the tiny bug fixes from the annoying/higher severity ones.


#13

Maybe a generic backport is good, and/or cricial_backport?
Bugzilla is pretty public. And the target numbers are nailed down by triage. So there was thought put into there. And there seem to be 3 types of bugs:

  • 5.4/master - minor bug.
  • 5.3.z - big bug.
  • anand/5.2.z - critical fix

Would be nice to have that information front and center.

  • filter PRs to ensure critical bugfixes go through the system as quickly as possible
  • change review process to assess risk of changes - e.g.: “good enough” or “this is too risky to add to anand”

#14

Part of the reason for this change was that we were sort of already doing this kind of thing, but in a really terrible way with a straight markdown file on ManageIQ/guides [1] [2]. However, this wasn’t really working. It requires a lot of manual effort, and doesn’t answer questions like “How far along in the sprint are we?” or “Can we fit this extra thing into the sprint?”

With GitHub milestones, we can organize all of that up front, and then modify it as we go along. It gives developers, the business unit, and the community the transparency it needs to make decisions and just generally know what is going on. Additionally, if we add the labels like “bug”, “enhancement”, we basically get everything we need to build a proper changelog, which is something we’ve wanted as well.

Annotation on the release tags isn’t bad, but it should be kept in mind that we are not only managing the releases with this…we are managing the sprints. There is no release (i.e. no tag) after a sprint. However, a number of sprints will make up the release cycle, and I can see many of the comments made above applying to the final release.

There can only be one milestone on a PR, so no, it’s not like a label in that sense. Also, 5.2, 5.3, etc are downstream terms and don’t belong in upstream. For backporting to release branches, I like the idea of maybe leveraging a tag. We’ll have to see.

Red Hat Bugzilla issues for CloudForms are public now (at least the new ones are), so there is nothing wrong with referencing a BZ issue to give more info about the change in question. Of course, some of them are still private, but that will be less and less as we move forward.

Botting a changelog directly from commit history is next to impossible. Since it’s for human consumption, a human would have to manually go through each commit/PR and summarize what was done. Incidentally, this is made A LOT easier with the milestones + labels, because it’s basically already broken down.

If you mean using annotated tags to automatically build a CHANGELOG.md, then I would say, let’s just put it in the CHANGELOG.md at the end of a sprint. When the release comes, it’s all ready.

This would be ok, and we can just remove the label when it’s backported. There is also the need to backport to upstream releases like anand. I believe @blomquisg did that in the most recent round of backports with a label called anand-merged so he could keep track what got moved over. Once it was all done, we just deleted the label. Note that labels are not infinite, so we should remove them when they don’t apply anymore.


#15

Thought you guys might be interested in this gem: Vandamme… “Vandamme is a changelog parser gem, used in the Gemnasium project.”

I’m putting together a CHANGELOG.md from the last sprint with the help of @marigold2048 . My thought is that after each sprint we take the contents of the sprint and add to the change log as “Unreleased”. When we hit the botvinnik release we should have a full set of changes, so we can just renamed “Unreleased” to “Botvinnik”.

In the Vandamme gem, there is a nice section on changelog conventions which I think I’m going to follow.