Recommendation: Breaking Changes Community Notifications

[eduncan911]

Hello! Because of what happened in #359, I'm opening a discussion to address breaking changes going forward.

Regolith is freakin' awesome. But, I think there's an opportunity here for things to be more proactive instead of reactive when it comes to these kind of changes or upgrades.

I think this is a great learning opportunity for Regolith support for the next "breaking" change to be announced a bit differently. So a few suggestions:

1. RSS or Twitter-like feed of breaking changes. Arch Linux used to have (but no longer!) a Twitter account for announcing breaking changes in their rolling releases. That's it. Short, clear, "X package needs Y work because Z will break" and a link for more info with a short command to run. They have switched to an RSS feed now for the same. Perhaps Regolith can have a "breaking change" similar RSS feed we can subscribe to and get alerts for - before we upgrade.

2. Add upgrade/changeme docs about the breaking changes and resolutions. However, this doesn't show / notify users too easily especially if every release just has a bunch of feature and bug fixes, where the breaking changes would be hidden way down in the notes (see Arch's dedicated channel notification above).

Also, are users really expected to stop their sudo apt update && sudo apt upgrade -y as instructed by 100s of blogs online for various apt installs - to notice Regolith wants to update, then stop and run to check out the Release notes of Regolith and dig in to see if anything breaks? Yeah, not the best way to let users know as it would force users to be Reactive, instead of Proactive: just like I did in this Issue! :) So we can cut down on the issue counts as well by not going this route.

3. Last thought, which I think may be the more feasible and automatic approach: force an aptitude Notes pop up with a required user interaction prompt - e.g. they have to read the break change notes, before aptitude can continue.

That last note... I didn't think was possible with aptitude until the Spectra and Meltdown patches and upgrades of Ubuntu 14.04 and it's old 3.X kernel, needing to force upgrade to 4.X kernel. But yet, the GRUB package forced that CLI prompt to force the user to decide on what action to take with their bootloader...

...which, I think was genius. No automatic breaking, no assumptions made by the package maintainers, and it directly involved user-interaction to make a decision.

Some other aptitude packages have also now popped-up a Notes field to tell users about a breaking change. Though, I've seen it more with Arch's pacman than I have with Debian/Ubuntu/aptitude over the decades.

Now, these pop-ups can break auto-update scripts on servers. But at the same time, Regolith is a desktop environment - not a server. So user interaction is expected.

[kgilmer]

@eduncan911 thank you for taking the time to write this up, very thoughtful with a lot of good ideas. In my mind, breaking updates is the #1 issue with Regolith, and has been since the beginning. A lot of this was due to me just not being able predict how users make changes to the system, and how those customizations manifest. But also, I think the nature of the i3 config file itself presents a problem. In a way, it's almost like a program that everyone tweaks to make their own, but also serves as a primary integration point for several of the components that make up Regolith. Due to it's monolithic nature, isolating changes by function or area is not possible. The best we have at this point is Xresources and 1.4 I think takes this to the limit. Other changes such as pluggable compositors, modular status indicator configurations, and Xres overridable Rofi config make this problem maybe less severe but unfortunately, fundamentals such as specifying which keybinding maps to what action can only be expressed directly in the i3 file (unless someone knows a way?) and so it's not likely that this problem will go away on it's own.

Regarding your suggestions, let me explain what we have now:

• Mailing list : this is where release announcements are made. I do not call out specifics in terms of breaking changes here, but simply list package updates. The announcements occur directly for package syncs, so there may not be enough time for users to become aware of coming upgrades.
• #release-plan slack channel : this is where "live" updates happen as to release news, for example pushing new packages to the release PPA or updating the website or releasing a new ISO.
• github issues : here we are on the front lines! This is where the problems and solutions happen, one-by-one.

I was not aware of a facility in Debian packaging that allows me to force user consent prior to a package upgrade. Can you provide some links, I did some searching but Debian packaging in general is notoriously bad for returning good search results, due to it's long legacy I'm guessing. In any case, certainly for any package introducing a breaking change, it would be very helpful for users to be able to make proactive decisions.

An idea I experimented with in R1.3 was to have version specific PPAs. This was intended as a way of letting users have more control over what updates they received. However, I found that bug fixes often require breaking changes to one degree or another, and so the version specific PPA became quickly out of date. I did not continue with this approach in R1.4.

Another consideration would be to do some post installation check at session login, determine if an upgrade happened since last login, and if so present a dialog with some content geared towards helping with issues.

In Regolith 1.1, I attempted an approach to automatically manage user's configuration copies by generating new, versioned copies with each package upgrade. This was a disaster and resulted in user configurations that I was unable to effectively debug. Based on this experience, I have become more conservative in what I can infer from a user's system. But, a passive dialog w/ a call to action would not be modifying user's state so I believe it should be safe. On the flip side, a key motivation for the design of Regolith is a reduction in dialogs, clutter, pop-ups, advertisements, etc. and would want to keep this sort of thing to a minimum, in situations where the utility clearly outweighs the user-experience cost.

Thanks again for your feedback and perhaps we can turn this into an RfC that I can announce on the mailing list and twitter to request more user feedback. What do you think?

[cheginit]

I think sticking to a release schedule would make it easier for users to know what to expect. For example, in the stable branch, there might be weekly patches and at the end of the month a minor release with breaking changes. Then every couple of months or so a major release. Following semantic versioning and emphasizing it in the documentation and announcements would help users to manage their expectations.

I know due to the fact that it's an open-source and community effort package following a release schedule might be difficult but it might be useful since it's an important part of the users' workflow and untimely breaking changes might cause discomfort and discourage the users.

Another idea could also be to add a command based on apt-mark hold for freezing all the regolith components, such as regolith freeze. So users have control over the updates. They can continue getting updates for all the other packages as usual and update Regolith only by unfreezing it. Or even taking a little bit further by freezing it by default and provide three commands for updates, for example, regolith patch, regolith update, regolith full-upgrade, for patch, minor and major updates, respectively.

[eduncan911]

Sorry for the delay!

@kgilmer I was not aware of a facility in Debian packaging that allows me to force user consent prior to a package upgrade. Can you provide some links

Took a good amount of digging, but I found a few pages.

Look at section 5.2.2 in this page:

https://debian-handbook.info/browse/stable/sect.package-meta-information.html

It says:

In general, the preinst script is executed prior to installation of the package, while postinst follows it. Likewise, prerm is invoked before removal of a package and postrm afterwards

Now, we can dig deeper by looking at this page:

https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html

It's a bit too much for someone who just came off an all-nighter. But, it does have a jump off finally to the nit and gritty:

https://www.debian.org/doc/debian-policy/ch-binary.html#s-maintscriptprompt

So it sounds like either the usage of one of, or a combination of using debconf and maybe config with template may be the way to achieve this.

As a reference of what I've seen, there are two types of prompts:

• One prompt just displayed a Notes file, where I had to press ENTER to exit. Kind of just a display notes.txt thing.
• I was once presented with a multi-choice option, where each choice configure the system differently (and drastically different too, it was Grub wanting to make different changes based on my input!).

Hopefully that helps.

I'll close the issue once you have decided a path forward or alike. :)

---

Sorry, on mobile... I'll have to get to the rest of the message later.

[kgilmer]

Hi @eduncan911 thanks for your detailed response and I hope you got some sleep!

Yep, from your links I see a path forward on how we could implement a manual "are you sure you want to upgrade" manual confirmation. Thanks for digging in and pulling that info out. A few complexities that come to mind from this approach are:

• Background or automated upgrades. The documentation recommends to have a default for unattended upgrades. If we do this then it's likely that some users that may wish not to upgrade won't see the prompt.
• User translations of confirmation message
• It's not feasible to compute if a given user will have problems with an update due to custom changes to their config, so this predicate must be applied to everyone.
• I guess without some kind of white/black list facility, every user would get this prompt for every upgrade. However the breaking changes in Regolith are due to custom configurations breaking against default configurations. So, users that have not updated their config files manually, or rely on Xres overrides, would not really need this dialog as their upgrades should not break them. But adding this prompt would require all users to explicitly opt-in.
• Perhaps I'm wrong but the prompt mechanism discussed here is primarily designed to get required configuration information for a package to be installed, not as a secondary check of "are you sure you want to install x/y/z" and so may be unexpected for users to encounter.

Based on this I think that @cheginit 's approach of using apt-mark to allow users to explicitly say "don't update anything from Regolith without my explicit opt-in" satisfies the original requirements but does not impose additional steps for users that may not care.

What do you think about this approach @eduncan911 ?

[kgilmer]

Closing given age. Symver, mainling list, and existing apt tools I think are sufficient to address the original concerns.

[eduncan911]

Thanks Ken. Yeah, things have been smooth sailing ever since this.