Mark breaking changes in Changlog

[joshka]

Documentation issue

Summary

Today I bumped my blog from 17.2 to 20. There are no breaking changes mentioned in the Changelog, so I figured this was probably going to be safe. I ran into three (so far) problems - generate_feed, feed_filename, get_url. So in order to understand whether there's a breaking change, I have to either read and understand every single change that was made or repeatedly play the deploy game until I succeed. Both are linear O(N) approaches to something which should be constant time O(1).

Proposed solution

1. Note breaking changes in the changelog (or some other easy to access file)
2. Include details about how to fix the issue in the doc
3. Backfill this with info about breaking changes in recent releases

Note: this is fairly simple to automate if you use conventional commits and a changelog generator like git-cliff. Slap a ! after the scope or add a BREAKING CHANGE: section in the commit body and make sure you use a template that notes the breaking changes.

[Keats]

Yeah I forgot to mark the feed changes in 0.19 in the changelog. What was the get_url breaking change?

[joshka]

I was running a version of the terminal theme that was fairly old. I had a redirect page setup in my content and running Zola serve stated that get_url required a page argument. There wasn't an obvious line of code that popped out where I was doing that, so I ended up just updating the theme.

Details of fixes in https://github.com/joshka/joshka.github.io/commits/main/ - grab the dependabot commit if you want a local repro. Check the failing GitHub actions for deploy logs. I tried a couple of times to fix via ci before resorting to a local check / fix.

I figure there's no outstanding problem here, so it's more about saving future upgrades from similar pain points.