Sxmo Project Goals and the sxmo_migrate.sh on Upgrades Flaw

Published 2022-02-04 on Anjan's Homepage

In every release of Sxmo, we have a message in the release notes stating the following:

This release brings a lot of changes to sxmo configuration files and hooks. Leaving your old configs can cause many issues so we recommend you run sxmo_migrate.sh as soon as you upgrade.

Users often do not read the release notes and join the irc channel to ask why their installs broke. Exploring this issue should explain Sxmo project goals to new users while providing context for Sxmo requiring this annoying manual intervention from the user. Moreover, in the upcoming postmarketOS stable release, we have a major improvement to this issue.

So lets begin with the first contribution I made to the Sxmo project. I asked Miles Alan (the maintainer at the time) whether he would accept patches that automatically set defaults that would make firefox work better on mobile ¹. He said it’s a good idea and that’s where the trouble began - we defined Sxmo to be a distribution of minimal tools (dwm/dunst/st, sway/mako/foot/swaybar) that come with sane defaults for mobile but are infinitely extensible by the user. The tension in our goals is between providing sane defaults for a set of tools that are developed independently of each other and still allowing for user extensibility. For example, the statusbar would be annoying to configure for the user in these minimal tools but users often want the same things (modem states 4G/3G/etc., wifi status, battery, etc.). On Sxmo, we have icons and everything just works by default. However, we still allow users to customize and add whatever statuses they want to the status bar or remove things they don’t care about. The problem arises when the maintainers want to push a new default they think is good and users must merge these changes to their customized changes. This problem happens across the Sxmo stack - we have a custom Sway config that enables hardware buttons, sets sway up to communicate with other tools in the stack, etc. If an update in an upstream project is pushed, Sxmo must change to make sure the default config works and provide a mechanism to send this change to user’s customized configurations.

So, what’s the solution? The value proposition of Sxmo is a system with sane defaults that’s infinitely extensible. If the user wanted a truly minimal solution with customizability - they can install the sway postmarketos ui metapackage and spend time customizing. They can mix and match the Sxmo utilities as most of them are usable outside of Sxmo and available as packages in Alpine Linux ². The goal of Sxmo is a distribution of minimal tools that creates a complete mobile environment so we looked into helping users apply the new defaults that maintainers had pushed.

To help in migration, it was suggested we automatically edit user config files to migrate them. This is not tenable because of how infinitely customizable Sxmo is and we would have a massive file made of sed commands that would override user’s files - most Sxmo users would not like this including me. In the other direction, it was suggested to make the configs more minimal and remove the default commands from the hooks for core functionality (ie. statusbar). The best part about Sxmo is the community sourced defaults are amazing - I installed Sxmo on my pinephone pro and pretty much everything worked out of the box except for some minor issues. This is before any of the Sxmo maintainers had a pinephone pro. Moreover, I am consistently impressed by the improvements to usability caused by new recommended defaults.

Here is the solution we eventually came up with: We created sxmo_migrate.sh which iterates through configs in the Sxmo stack and alerts users about the diffs between the default configuration and the config in their home directory. Again, sometime these default config changes a critical so that programs in the stack can communicate with each other and work together with the new version of the scripts. Many users would forget to run sxmo_migrate.sh and end up with installs that didn’t have stuff working thinking it was a bug in Sxmo.

So for the 1.8.1 release that will be in postmarketOS stable, we have modified sxmo_migrate.sh to save users that don’t read the release notes. We now put a # configversion: in each config and if the default configuration gets changed, the configversion in the default config will get incremented by the maintainers. If the user’s configversion is different than the configversion in the latest default config, we will use the default configuration for that program until the user runs sxmo_migrate.sh. Only files with configversion incremented are shown and this prevents the firehose of config changes that users had to experience before. After all, it is unlikely that your custom dunst config when Sxmo hasn’t changed the dunst config will break anything. The user can run sxmo_migrate.sh all to compare diffs of all the configurations and sxmo_migrate.sh reset to removes all user hooks and revert to default configurations. The default start hook has been updated to alert the user when we have moved files in favor of defaults and how to migrate their configs. Users should always upgrade Sxmo if and only if they have time to fix potential issues with their hooks and configs. You can look at the whole patch and documentation of this feature here:

Patch

https://git.sr.ht/~mil/sxmo-utils/commit/1c07327fd84597f8702c3e6df2f5c9e155617e98#configs/default_hooks/start

Documenation

https://man.sr.ht/~anjan/sxmo-docs-next/USERGUIDE.md#strongupdate-migrationsstrong

I was very hesitant to put 1.8.0 release into postmarketOS stable because of this issue but Im happy we finally found a dare I say, okay solution. PostmarketOS will soon allow for upgrading between stable releases so we could not postphone this issue for a major release. The pine64 survey showed a large number of people daily driving Sxmo on postmarketOS. I am so happy that many people find Sxmo useful and I think this popularity is because we provide sane defaults to show off how easy Linux Mobile can be while allowing for extensibility that users could never get on an Android or Iphone. Moreover the minimal stack runs well on phones with few resources. Sxmo will still get out of your way if you write a custom hook but it will now be more insistent that you check the defaults on upgrades so you don’t run into unnecessary bugs. I remember when I first started using Sxmo and if I ran into issues, I could not ask anyone for help. I don’t want Sxmo to be a practice in obscurantism because more users means more modem testing, better upstream projects, more code contributions, and better help when I run into issues - I am somewhat selfish afterall. At the same time, I don’t want Sxmo lose its appeal among the most technical users that will help improve mobile Linux. Nowadays, we have over 100 people in the irc channel and it’s a helpful and wholesome community for learning and working together.

Thanks for reading to this post! I hope this explains the sxmo_migrate.sh inconvenience when using Sxmo and I hope you continue to find Sxmo useful!

Have a comment on one of my posts? Start a discussion in my public inbox by sending an email to ~anjan/public-inbox@lists.sr.ht [mailing list etiquette]