Introducing breaking changes in softer way

Two recent breaking features come to my mind:

  1. New way of iterating over content which broke multiple older themes (don’t remember which version)
  2. Goldmark renderer breaking HTML inside content

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? :slight_smile:

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.