Changing the way we use milestones in the issue tracker

300 views
Skip to first unread message

Andrew David Wong

unread,
Aug 9, 2023, 2:06:41 AM8/9/23
to qubes-devel, qubes-users
## 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: https://www.qubes-os.org/doc/issue-tracking/#milestones

jma...@tutanota.com

unread,
Aug 9, 2023, 9:36:08 AM8/9/23
to Qubes Devel
I think that the new tag/milestone system is way better and logical, well done. And arguments are quite convincing to me.

I would like to add an idea about official templates. We know that there are bugs in the templates, including the latest one fedora-38 or fedora-38-minimal. Maybe you can consider tags (labels) in the same manner as with released, e.g.: `affects-f37`, `affects-f38`, `affects-f38min`, `affects-d11` (for Debian) and etc.
The reason - bug or problem in the official template is the same for R4.1 and R4.2 (or am I wrong?) and, thus, is not a release-version-depended bug.

When new release of official fedora template comes out it changes the situation every time: some new bugs are introduced, some are fixed without afford of the Team by Fedora/Debian guys. Tracking this could be useful.

Templates also have EOL, which could lead to closing outdated inactive tickets in the same manner as with `affected-4.0` tags. And template's EOL is not directly connected to Qubes OS version but more with Fedora project and their EOL rules.


--
Best regards,
jamke



Aug 9, 2023, 06:06 by a...@qubes-os.org:
> --
> You received this message because you are subscribed to the Google Groups "qubes-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to qubes-devel...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-devel/6987bd94-817c-f216-e923-0d3029723f43%40qubes-os.org.
>

Andrew David Wong

unread,
Aug 9, 2023, 9:52:56 AM8/9/23
to jma...@tutanota.com, Qubes Devel
On 8/9/23 6:36 AM, jmake2 via qubes-devel wrote:
> I think that the new tag/milestone system is way better and logical, well done. And arguments are quite convincing to me.
>
> I would like to add an idea about official templates. We know that there are bugs in the templates, including the latest one fedora-38 or fedora-38-minimal. Maybe you can consider tags (labels) in the same manner as with released, e.g.: `affects-f37`, `affects-f38`, `affects-f38min`, `affects-d11` (for Debian) and etc.
> The reason - bug or problem in the official template is the same for R4.1 and R4.2 (or am I wrong?) and, thus, is not a release-version-depended bug.
>
> When new release of official fedora template comes out it changes the situation every time: some new bugs are introduced, some are fixed without afford of the Team by Fedora/Debian guys. Tracking this could be useful.
>
> Templates also have EOL, which could lead to closing outdated inactive tickets in the same manner as with `affected-4.0` tags. And template's EOL is not directly connected to Qubes OS version but more with Fedora project and their EOL rules.
>
>
> --
> Best regards,
> jamke
>

Good point! I agree; it makes sense to track whether a bug affects a specific template version independently of the Qubes OS release on which that template happens to be used, especially when that template is supported on multiple Qubes OS releases.

(P.S. -- The convention on these mailing lists is to used interleaved or bottom-posting rather than top-posting.)

Marek Marczykowski-Górecki

unread,
Aug 9, 2023, 10:13:33 AM8/9/23
to jma...@tutanota.com, Qubes Devel
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Wed, Aug 09, 2023 at 03:36:03PM +0200, jmake2 via qubes-devel wrote:
> I think that the new tag/milestone system is way better and logical, well done. And arguments are quite convincing to me.
>
> I would like to add an idea about official templates. We know that there are bugs in the templates, including the latest one fedora-38 or fedora-38-minimal. Maybe you can consider tags (labels) in the same manner as with released, e.g.: `affects-f37`, `affects-f38`, `affects-f38min`, `affects-d11` (for Debian) and etc.
> The reason - bug or problem in the official template is the same for R4.1 and R4.2 (or am I wrong?) and, thus, is not a release-version-depended bug.

Generally, we don't track non-qubes bugs in our tracker (there are
exceptions, but still). And qubes packages are specific to qubes release
in most cases (so, a fix in one release doesn't make it automatically
fixed in another). So, such label would still need to be combined with
affects-4.1 or similar. We also have "C: Fedora"/"C: Debian" labels
which serve similar purpose (but without specific version).
So, generally an issue that would affect just a single version of a
template (for example f37 but not f38) is either:
- an issue in a software [version] specific to that template, not to
qubes - in which case it should be tracked in that distribution
tracker
- a compatibility issue in qubes package connected with specific
template version (like, some qubes package misbehave when using
libfoo version 2.0, but works fine with version 1.0)

The latter case might warrant label specific to template version, but
would still require also a label specific to qubes version. It might be
useful for testing template versions (like debian-12 right now), but
in that case we encourage to simply mention template-tracking issue, so
it gets linked by github. As for bugs affecting only older template
versions but not newer (so, they stop being relevant when said template
goes EOL), I have an impression those are rare, but maybe I'm wrong?
Andrew, do you think it's worth it?
> To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-devel/NbPVjTN--3-9%40tutanota.com.

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmTTnwUACgkQ24/THMrX
1yzpSwf+OvC4uOCQjLKsOZyzAVPGpoDkzizF0NScXodGysRxfjnrUlK4DbLGZ/Uz
lHfCZjshDP19YjTaGBMtFx0+5LZVtUsn/LufbpSTQAFZ3eInnyI3ggIuuSW5Ru1m
4n29/t147A+RmMQn2TL4z8hP7DDSyYGdxqLIE26/IvukWrfvAlBQPlMIov1FRf4D
lHloo7LmNQFa19flf6yoCluRPrP1OLjQyh71+KsGnWlR1f+eZ4tLBiINrv3Sb9zd
mcqBgsEkTtFtATbLYDSP7zJMkef5WrLOcZkoeMpwk2YBTwpPW+EC3wYzm635wcby
hc3ZGqBAVv4CPG5HTs+8dfy03DOj0A==
=gHO0
-----END PGP SIGNATURE-----

Andrew David Wong

unread,
Aug 9, 2023, 10:42:38 AM8/9/23
to Marek Marczykowski-Górecki, jma...@tutanota.com, Qubes Devel
Oh, my mistake. It sounds like templates are more Qubes-version-dependent than I realized. In that case, I think you're right that it may not be worth it, given we already track both Qubes release and general template type with existing labels.

jma...@tutanota.com

unread,
Aug 9, 2023, 11:22:39 AM8/9/23
to Marek Marczykowski-Górecki, Qubes Devel
Aug 9, 2023, 14:13 by marm...@invisiblethingslab.com:
Well, I see Marek's point. I agree, that if the problem happens to be upstream it should be closed with not-our-bug or something. And it happens this way now quite often.
But note that Qubes OS users search for their issue and it's better they find closed ticket than no ticket at all. And when people report, most of them are not able to reliably check what happens in the original Fedora that they do not have. That is why all major GNU/Linux distos still keep issues in software that is made by third-party developers, it is a common practice after all.

If the issue affects software behaviour under Qubes OS in f3* in most cases it is not limited to R4.0, R4.1, R4.2, in my experience. I still remember the funny case when brand-new fedora-29-minimal was released to the public without `e2fsprogs` package and it made template completely not possible to run, not even open xterm, quite a f29min specific issue :)

For more than 5 years I have to make my own KDE templates based on fedora-*-minimal and I am certain that each and every single one of new Fedora releases solves several existing issues for me personally (that I had to fix or workaround myself), and each release introduces new problems, too, no exceptions. So, this bugs are template-version-specific, nothing to do with Qubes OS version after all, and those a common, to my non-standard experience.

Some of my template-only-related issues:

Qubes not processing application icons correctly (likely due to different icon sizes) · Issue #6292
https://github.com/QubesOS/qubes-issues/issues/6292

Remove GNOME Tracker from the Minimal templates of Fedora (e.g. `fedora-38-minimal`) · Issue #8403
https://github.com/QubesOS/qubes-issues/issues/8403

`bash-completion` package missing from Fedora template · Issue #8394
https://github.com/QubesOS/qubes-issues/issues/8394

fedora-38 template has gnome-control-center (GNOME Settings) that does not open. · Issue #8393
https://github.com/QubesOS/qubes-issues/issues/8393

Other people have it, too, just today I saw that on forum:
https://forum.qubes-os.org/t/thunderbird-may-crash-on-fedora-38/20289/2


I can provide a couple of dozens issues related to fedora templates (most issues are Qubes OS specific), but quite possible that total number of ongoing template issues is still not that much to have template version separation. In this case I agree that it is really not needed to have template labels at all.

One the other hand, if the issue is related to f38 only, does it affect R4.2? Currently it does, and it also does affect R4.1, but what will happen when f39 comes out and f38 is EOL? How will it be removed from the affects-4.2 group? Only manually for each of them.


Well, anyway, the new system is better, milestones were really confusing for me. Thanks for changes!


P.S. About bottom-posting: sorry. I remember quite old posts about why it is almost the only proper way to do (Joanna's?), but my web client for email that I use for this mailing list is making usage of mailing lists so painful, that I struggle.


--
Best regards,
jamke



Andrew David Wong

unread,
Aug 10, 2023, 3:18:58 AM8/10/23
to jma...@tutanota.com, Marek Marczykowski-Górecki, Qubes Devel
On 8/9/23 8:22 AM, jmake2 via qubes-devel wrote:
> [...]
> Well, I see Marek's point. I agree, that if the problem happens to be upstream it should be closed with not-our-bug or something. And it happens this way now quite often.
> But note that Qubes OS users search for their issue and it's better they find closed ticket than no ticket at all. And when people report, most of them are not able to reliably check what happens in the original Fedora that they do not have. That is why all major GNU/Linux distos still keep issues in software that is made by third-party developers, it is a common practice after all.
>

If you really want to open issues that you know are not Qubes bugs in the Qubes issue tracker for this reason, I suppose you can just make it clear when you open such issues that they should be closed as "not our bug," and I'll just immediately close them with that resolution. Seems a bit odd to me, but I suppose it's relatively harmless.

> [...]
> One the other hand, if the issue is related to f38 only, does it affect R4.2? Currently it does, and it also does affect R4.1, but what will happen when f39 comes out and f38 is EOL? How will it be removed from the affects-4.2 group? Only manually for each of them.
>

In that scenario, we would simply close that F38-specific issue, since F38 has reached EOL. We wouldn't have to worry about removing the "affects-4.2" label, because the issue would be closed now anyway. (I think it's fine to have the "affects-4.2" label on a closed issue that once affected 4.2.)

jma...@tutanota.com

unread,
Aug 10, 2023, 6:45:16 AM8/10/23
to Andrew David Wong, Qubes Devel
Aug 10, 2023, 07:18 by a...@qubes-os.org:
Well, maybe I am wrong, maybe it is not a good idea to track third-party issues that affect Qubes OS (even closed). I do not know.

GNU/Linux distributions do it, but most of them are bigger, not a problem for them to allow such issues.

--
Best regards,
jamke






Andrew David Wong

unread,
Aug 10, 2023, 6:15:22 PM8/10/23
to jma...@tutanota.com, Qubes Devel
We also allow them, but we close them as "not our bug" because that's what they are, and because they're not actionable for us.

Andrew David Wong

unread,
Oct 31, 2023, 10:50:00 PM10/31/23
to qubes-devel
On 8/8/23 11:06 PM, Andrew David Wong wrote:
> ## 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.
>
> [...]

Okay, after trying this new system for a while, I see that there are still some problems:

1. Milestones are still confusing. It's still not intuitive to some people what it means for an issue to be on a milestone and when an issue should be added to a milestone.

2. Adding issues to milestones doesn't fit into the dev workflow. For some devs, adding the issues they plan to do to a milestone doesn't come naturally. Others add issues to milestones before checking with the release manager. I often end up having to remove issues from milestones that aren't approved and having to add closed issues to milestones that should have been there. All of this tells me that the milestone system isn't working well. That's okay. If it doesn't come naturally, it shouldn't be forced. This system is designed to help the devs, so we should tailor it to their workflow rather than the other way around.

3. Milestones are too similar to `affects-*` labels. The intended distinction is: `affects-*` = affects that release. Milestone = plan to do for that release. The former seems to be a lot more intuitive for people than the latter.

So, what should we do about it? I propose we just get rid of milestones. Stop using them completely. (Just because a feature exists doesn't mean we have to use it.)

What will we lose if we stop using milestones? From my perspective, not much:

4. It would be harder for the general public to see "how much work remains" before a given release. However, given (2) above, milestones aren't accurately representing this in the first place, so there's no real loss here.

5. It would be harder for us to see which issues we have done for a given release. For example, I used a search of all completed issues on the 4.2 milestone since RC3 to come up with the list of changes between RC3 and RC4. But there are potentially better ways to handle this. For example, we could just have an additional label like `merged-for-4.2` or something, which might be more intuitively understandable.
Reply all
Reply to author
Forward
0 new messages