Both of them were introduced before any previous notifications, so multiple users (including me, both times) updated Hugo, built website and uploaded it after changing little things and only later realising that their page is broken.
While the changes themselves are OK, I think the way they’re introduced could be improved.
Standard practice is to issue warnings during compilation when something is going to be deprecated soon. It would remedy lot of pain for many people surprised by those changes coming out of nowhere.
Secondly, I think those breaking changes should be more prominent within release notes themselves. Example from 0.60.0:
Also, if you have lots of inline HTML in your Markdown files, you may have to enable the unsafe mode:
Sounds like not very important side note, but actually tells about something very big for many people. Just bolding this text would do wonders.
In before “RTFM before updating”, I believe what I described above is just common sense and being nice to users. We don’t follow release notes, news and monitor every change, so it’s very easy to be caught with pants down.
I initially agreed so I liked the post, but can’t take it away anymore. But now that I thought about it I’m not on board.
I think it’s the responsibility of the user to read the whole release notes. The second breaking change you mention was in the release notes, and even called out with a small example. That’s pretty decent. Because it could also have been buried in the list with Github commits.
So if the information is there we can’t really complain, right?
Do I agree that updating Hugo is a pain because it requires reading all the release notes and then testing all websites in detail? Yes. But updating any software takes a lot of time and energy, unfortunately.
Shouldn’t you just be using the version that is compatible, and then upgrade once you’ve converted your templates? That is why they have versioned releases.
So, we (I) try to behave good in this department. Most deprecation will live for a long time before removed. For the .Pages change we had no way to “keep the old” without creating a really ugly API – so we released one version with a deprecation warning saying that “In the next version this will change”, which obviously didn’t help if you skipped a few updates.
What I’m saying that I don’t like breaking peoples’ sites, because then they come here and ask about it, which creates work. But it’s hard to avoid it completely if you want to move forward, and esp. consider our rather limited developer budget. We are not Microsoft.
@bep I think it would be reasonable if Hugo threw an error/info upon build that some HTML was omitted. It’s very easy to miss. Even if someone decides that they don’t want to use unsafe mode and HTML in .md files is no longer allowed, this can be difficult to enforce and track in a page with more contributors, so a message during build would be very welcome.
As somebody who updates their Hugo sites (and therefore Hugo) infrequently, I think the breaking changes could be handled in a much better manner.
There doesn’t seem to be a single place for me to go to get a changelog for everything between the version I was using previously (assuming I know what that is) and the version I just updated, let alone what broke, and how to accomodate those changes.
The release schedule is such that I just went past 20 versions, and apparently I’m just supposed to click on blog posts for each of those and parse out "oh the default markdown renderer changed, and I just spent two hours getting to the point where I learned what I needed to do is change the renderer settings.
While Hugo has a lot of power, it honestly feels to me like my time would be better invested in migrating to something with a more stable behavior across versions, that doesn’t require hours of figuring out what broke this time and accomodating that, before I can proceed to actually doing the content updates I want.
Well I am unaware of any software that can detect whether a project contains outdated code and give you a detailed changelog.
I am afraid that you need to invest the time in maintaining your projects just like the rest of us, even more so if you upgrade from a very old version.
Breaking changes usually come after being announced -there was an instance when such a change was introduced by accident but then this was reverted and the change was pushed to a later version-.
There will be more breaking changes down the line. Typically deprecated features throw console warnings.
Console warnings do not break a project but one needs to spend the time to remove them because at some point the project will break in a future version.
However if time is so important, you can always choose to stay with the last version that outputs a working project.
Hugo simply outputs static HTML and its assets, one could use Hugo 0.16 released in 2015 and still publish a website today.
You know, simply having the release notes in an easily-scannable, machine-searchable changelog file (instead of on the blog) would go a long way towards helping me figure out what breaking changes there have been. But hugo doesn’t keep a changelog file.
I received no console warnings about goldmark or whatever it was called swallowing my inline html.
Regardless, you’ve convinced me not to invest any more time in hugo. Thanks!
I have thought about this and I don’t think that Hugo has more breaking changes per year compared to other comparable software (I will claim that with Hugo’s static binaries, robust versioning, no plugins that it’s in a much better state in this area than some JS alternatives; and I have seen Hugo sites built for ancient version run fine on the latest Hugo (simple sites, I’ll admit)).
But, while the “others” are doing more waterfall style of development with new major releases every n year, that is not the case with Hugo.
Which, when you go from 0.30 to 0.72 and your build fails, it gets a little needle in the haystack to find the relevant notes in the release notes – even if there were only 3 potentially breaking changes in that period.
What we could and should do is to create a separate page in the docs site where we list all potentially breaking changes grouped per version and also, if possible, a “what to do to get get around this”.
If someone wants to start on such a page, a PR is welcomed.
