## Summary
Issues will no longer be assigned to milestones by default. Most issues won't have milestones. The Qubes developers will manually assign issues to milestones. We'll use labels like "affects-4.1" and "affects-4.2" to represent affected releases instead of milestones. The "Release TBD" and "Non-release" milestones are being phased out, as are milestones of the form "Release X.Y updates." Read on for a more detailed explanation.
## How milestones work right now
Currently, our milestone guidelines are as follows:
- Every issue should be assigned to *exactly one* milestone.
- For *bug reports*, the milestone designates the *earliest supported release* in which that bug is believed to exist.
- For *enhancements* and *tasks*, the milestone indicates that the goal is to implement or do that thing *in* or *for* that release.
For example, if you were to report a bug that affects both 4.1 and 4.2 right now, it would be assigned to the "Release 4.1 updates" milestone, because 4.1 is the earliest supported release that the bug is believed to affect. As another example, if you were to open an enhancement issue right now, it would most likely be assigned to the "Release TBD" milestone, which means something like, "This enhancement, if it is ever implemented, will be implement in some Qubes release or other, but it has not yet been determined which specific Qubes release that will be." If it were decided that this enhancement would be implemented for 4.2, for example, then the issue's milestone would be changed to "Release 4.2."
## Problems with the current system
Some people find our current use of milestones to be counterintuitive. For example, suppose that a bug is reported that affects both 4.1 and 4.2. The Qubes devs decide that it's not too serious, so it's okay just to fix it in 4.2 and leave it be in 4.1. Some people have the intuition that the issue should be reassigned to the 4.2 milestone, since the devs just decided that's where it'll be fixed. However, under the current rules, that would be wrong, since the bug still affects 4.1, and 4.1 is the earliest affected supported release.
Similarly, suppose that someone reported a bug against 4.0, but it's one of those "we'll get around to fixing it someday, maybe" sort of bugs. Some people would be tempted to assign this issue to the "Release TBD" milestone on the grounds that the plan is to fix it at some yet-to-be-determined point in the distant future. However, this would again be wrong under the current rules, since the milestone for a bug report is supposed to represent the earliest supported release in which the bug is believed to exist, which is 4.0.
The current method also presents problems when it comes time to close old issues. As many of you have probably noticed, I recently closed a large number of issues that were on the "Release 4.0 updates" milestone, since 4.0 reached EOL over one year ago, and those issues had not seen any activity in over a year. The problem arises when an issue affects more than one release. For example, there were some issues that affected both 4.0 and 4.1. In accordance with our milestone rules, those issues were assigned to the 4.0 milestone. When it came time to bulk-close the old 4.0 issues, issues were closed even though they also affect 4.1, which is still supported. The fact that those issues also affect 4.1 wasn't represented in a label or milestone (just in a free-text comment), so I had no way to filter them out when performing the bulk close action.
Finally, each milestone has a progress indicator that shows the percentage of completed issues on that milestone, but this indicator isn't very useful when every issue that affects a given release gets assigned to that milestone, regardless of whether the devs actually plan to act on it. When every release ships with a partially-completed milestone, it becomes an unreliable indicator.
## Analyzing the nature of milestones
Let's step back for a moment and think about what milestones are and what purpose they're supposed to serve. An issue tracking system doesn't actually *have* to have milestones at all. They're an optional feature. All an issue tracking system really needs is a single type of "tag" functionality (what GitHub calls "labels"). You can re-create almost any other type of issue tracking functionality (including milestones) with just tags. From this perspective, GitHub's milestones are basically the same as labels, except for two distinctive features:
- Unlike labels, milestones are mutually exclusive. An issue can have an unlimited number of labels, but it can be assigned to at most one milestone.
- Unlike labels, milestones have progress indicators.
So, if we're going to use milestones, it makes sense to use them in a way that takes advantage of these distinctive features.
## How we plan to use milestones going forward
Issues will no longer immediately be assigned to milestones. Instead, when the Qubes developers decide that they (or a contributor) will complete an issue for a certain release, they will assign that issue to the corresponding release milestone. This means that most issues won't be on a milestone at all. Instead of "every issue is on some milestone" as the default, it will be "no issue is on a milestone by default." Instead of each milestone containing all issues that are relevant to it, each milestone will contain a hand-picked selection of issues on which an authority has decided action will be taken for a specific Qubes release.
We believe that this "curated list" approach to milestones will make them much more useful. With the current "kitchen sink" approach of each milestone containing every bug report ever filed for that release, each milestone contains many issues that the Qubes devs haven't even had time to diagnose. With the new approach, you can be confident that the Qubes devs have not only looked at and considered each issue in a given milestones; they've actually decided that action will be taken on that issue and plan for it to be done for that release! (Of course, the Qubes devs reserve the right to modify or remove milestones at any point at their discretion. Assigning an issue to a milestone isn't a binding commitment of any kind, and the realities of the software development process guarantee that milestone assignments will often change.)
A side benefit of this new system is that it makes it clearer that every issue opened is merely "under consideration" until the Qubes developers approve of it and decide to act on it. (Even under the old system, assigning a bug report to the "Release 4.1. updates" milestone, for example, doesn't mean the Qubes developers plan to act on it or even that they agree that it's really a bug in 4.1.)
Since we will no longer be using milestones to represent which release(s) a bug affects, we'll instead use labels like "affects-4.1" and "affects-4.2." This will allow us to accurately track cases in which a bug affects multiple releases. (I expect that "affects-*" labels will be used mostly with bug reports, but there are probably some cases in which they can sensibly apply to tasks and enhancements.)
We currently have a milestone called "Non-release," which is for issues that are independent of the Qubes OS release cycle, such as website, documentation, and project management issues. This milestone provides little value and will be phased out. The main reason it existed under the old system is to satisfy the "every issue must be assigned to a milestone" rule, but it's actually redundant with labels like "C: doc."
Similarly, we currently have the "Release TBD" milestone, which is for enhancements and tasks that will (or would) be specific to a Qubes OS release but have yet to be assigned to a specific release milestone. This milestone makes no sense under the new system, as *every* issue is in this state by default until it is hand-selected for inclusion in a specific release milestone.
Finally, we have milestones like "Release 4.1 updates" (as opposed to just "Release 4.1"). Under the old system, these "* updates" milestones were used to collect issues (mostly bug reports) that were filed after the corresponding stable version was released (in this case, 4.1). In other words, all 4.1 bugs reported during the testing stages were assigned to "Release 4.1," then the stable 4.1 release was announced, the "Release 4.1" milestone was closed, and the "Release 4.1 updates" milestone was opened in its place. (In practice, it was already open by this point.) All "Release 4.1" bug reports that were still open and all subsequent 4.1 bug reports from that point onward were assigned to this "Release 4.1 updates" milestone instead. (In some cases, some bugs that the devs knew they wouldn't fix in time for the 4.1 release might've been assigned to "Release 4.1 updates" early.) Not only is this process confusing to newcomers (because the distinction between "Release 4.1" and "Release 4.1 updates" is too subtle); it also renders the progress indicator on the "Release 4.1 updates" milestone fairly meaningless, as it is attempting to track progress on updating a version that has already been released, which is a never-ending process until that release reaches EOL. These "* updates" milestones are also being phased out.
Thanks for reading! To view the latest milestone guidelines at any given time, please see: Issue tracking | Qubes OS