Talking about how one updates a tool may seem a bit nonsensical, after all, what dificutlies can you have when updating a tool? Well, you would be surprised! But no, this post is not about issues when updating swiftformat. Quite the opposite!

I just have praises for swiftformat, it's an amazing tool. This post is just a description of the process I follow when I have to update it. The way I want to configure the tool seems to be a little out of the ordinary, so after the years I've developed a specific process with various steps. As with many things, I just have this process interiorised and I do it automatically every time I'm working on an update. But once you sit down and write it down, something I did for the internal documentation of my team, you realise that is quite involved.

The principal reason for such as process is because I want to have full control of the options and changes of the tool, something that is usually the opposite of what authors want. And that's not something bad. A tool needs to be easy to use, it needs to be ready in a couple of steps. And that works fine for most people, but I want to know exactly what rules are being applied at all times. That's why I check the changes on every update and have the configuration the way I have it.

The process

Configuration

The configuration file is set up in a way that allows me to have full control of the rules and makes it easier to update. This allows me to know exactly what will happen when formatting and don’t let new versions touch code without explicit consent.

Thankfully, swiftformat has a way to make all the rules opt-in. Which is great because this means I must specify all the rules I want, even if they would be enabled by default.

Another important point is that all the rules are listed, the ones I don’t want are commented with a reason of why they are not enabled. This helps a lot when in a future update the reason is no longer valid, because of a fix or a new option.

I also keep the list of rules ordered alphabetically, this makes it easier to detect if you already have a rule or not. In theory it shouldn't be necessary since all rules are listed, but it wouldn't be the first time I missed one!

After all the rules, there is a list of options. As with the rules, this list is ordered and contains all options, with the ones I don’t want commented and with a reason.

It’s very important that this configuration is kept with these rules, to summarise:

• First rules, then options.
• Ordered alphabetically.
• All are present, the ones I don’t want are commented with a reason.

Update process

1. Check the time it takes tor run

Before changing the version or the configuration is necessary to record the time it takes to run in order to detect vast increases. This is quite important since with our big codebase any process takes quite a bunch of time, so I want to keep an eye to make sure it doesn't get disproportionally worse.

I use hyperfine to benchmark command-line tools.

2. Check the changelog

First, I check the version that is installed by running:

./swiftformat --version

Then I go to the releases page and check how many releases have been since last time. At this point I take a first glance at the changes to detect any major breaking things that could block me later.

3. Update each version

Yes, I update each version one at a time. This is very important since I want to see what changes every version introduces and go step by step. Sometimes fixes in a version change the way things look and is very hard to detect where is the problem if you change multiple versions at once.

3.1 Update the binary

On each release page there is a binary attached. This is very convenient because I like to keep the binaries in the project to make sure everybody is running the same version of the tool.

3.2 Give it a try

I then run sh format.sh (a small script that runs the formatter) to see changes. Ideally nothing would have changed between versions, but sometimes there are changes that are actually desirable, due to a bugfix on the tool.

If everything looks good, I keep going.

Otherwise, if the format changes to an undesirable state, there are multiple things that I often do:

• Check the changelog for related fixes in upcoming versions. If there is a newer version with a potential fix I just finish the update for this version and go to the next one.
• Check if a new rule or option has been added that would allow me to keep the old format.
• If the format is broken after trying the recent version, I raise an issue on the repo and don’t update yet. The author is so responsive than usually there is a fix pretty quick.

3.3 Update rules

I then check the changelog of that version for any mention of rules and options.

If there is a new rule or option, I give it a try and decide with the team what we want to do with it. If the team decides to add the rule, I make a note and do it in a separate PR (unless doesn’t affect much code). Remember that no matter if is enabled or disabled, the rule needs to be added to the config file (with explanation if disabled).

If there is an existing rule or option mentioned, I check if I have it disabled. If the changes on the rule would fix the reasons I had to disable it, I talk with the team to decide if we want to enable it now.

3.4 Commit the changes

This helps the PR review by having a trace of which changes were done in each version.

Conclusion

I follow this process step by step so I know exactly what are the new changes and I can take proper decisions. It takes a bit more time that just updating willy-nilly but for me is totally worth.