Is it safe always to use newer hugo versions for an existing code base,
or it may break things that already work?
That’s a very open ended question.
Personally: if my current version has all the features I need, I usually stay with it.
I mean
- did it ever break? is it safe to upgrade usually?
- did the developer say ever about future versions?
I suppose it never happened.
So, if it will ever happen, I suppose there will be some way to be protected,
like declaring an “API compatibility level” or something at config.toml,
so to have the appropriate warnings during running hugo.
Yes, newer versions of hugo may break sites that build with earlier versions. If it’s not point.point (i.e. bug fixes only) release, make sure you read the release notes.
I believe that is true in general for any X:
Is it possible that a new version of X breaks how it supposed to work in its older version?
Yes
- If you are happy with a version of X, stick with it. (With X==Hugo, it’s pretty easy to do so as it’s a single static binary.)
- Don’t upgrade unless you really need a newer version or are an upgrade junkie (like me ;))
- If you upgrade, make sure you read all the release notes and understand them before upgrading.
- It would also be nice to be ready to open issue tickets for any regression you see in the behavior of X after upgrading, with an easy to follow recipe to reproduce the issue.
1 Like
Usually various projects inform when backwards compatibility breaks.
For example in major releases or in beta.
So, at what kind of situation is hugo right now? It is considered stable or beta?
And when it is supposed to introduce breaking changes?
Is there any official policy by developers?
Hugo uses Semver. Hugo’s version starts with 0. That means it will change often and is not a finished product. Patch changes (0.56.1 to 0.56.2) shouldn’t break anything. Minor changes (0.56 to 0.57) might introduce incompatible changes and major changes (0 to 1) will be either “initial release” or a complete rewrite with lots of changes.
So to answer the “policy” question: yep, but that doesn’t help you with changes, because Hugo is not declared a finished product yet. As far as I understand. @bep might have some clarifying words about that, but that’s the short version of it.
4 Likes
So, essentially I must note somewhere the hugo version that I used and keep multiple hugo versions in the path. Right?
The changes to Hugo are quite well explained each time a new version comes out. At the end of the short summary you have a list of detailed items that changed. I am deploying to Netlify, so I always have a note of the currently used version of Hugo in my netlify.toml 
On the other side I use the Snap package of Hugo, so I always have the latest version.
It’s essentially a list of features and pages that I “test” after each update. If something looks weird I dive in. If it throws errors I search the forum here.
The last Hugo jump was the first time anything “broke” in my setup, but it also was basically a complete rewrite for the modules system.
I would update everytime a new version comes up. Better than having to re-read 6 month worth of release notes (I had to do that on one site recently. Lot’s changed since then 
)
2 Likes
Just to confirm: I, too, always use the latest version—locally at least.
If a new version should break something (in my case it also just happened once) very few and very easy changes to your existing theme should do.
If a problem occurs just remember that you develop a static website locally. Just fix calmly and then publish your website.
If you need to publish a website very urgently just go back to an older version of Hugo and fix the problem later.
Just compare this to working with a live WordPress installation You will love the Hugo workflow!
4 Likes
Exactly. If you are using Git to store your website you can “tag” working versions and get back to them very fast in case of emergency. Those tags don’t use up any space, so you can have hundreds (I have one tag per blogpost), they are just pointers to a version.
1 Like
That’s interesting, Patrick.
Could you give a brief example of how to use tags (for blog posts)?
I do use tags for versioning releases, yet I have never found other use cases. That’s why I am interested.
Thanks in advance!
For a while I had a job that increased the patch release number when I pushed updates to the repo. It basically went like this:
- update semver (some grunt script)
- add commit (
git add -A && git commit -m "chore: tag version ###") - push tag (
git push --tags) - push all (
git push --all)
The last line then resulted in netlify deploying.
The grunt script was nice, but I am not using it anymore… Let me check if I find it. Today I am doing it mostly by hand.
My versions are done like 2019.1.1234. First the year, then an arbitrary number that I increase when I think I did something bigger (like adding a search function or reworking the pipes), then an increasing integer. I start the patch version at 100 or 1000 because this way the tags get nicely sorted when I type git tag to see what the last version was.
Thinking about it, this might be a nice thing for my pre-push hook. I’ll try to recreate this and post it in Tips and Tricks.
2 Likes
Thank you very much for your detailed answer. Really appreciate it.
That’s a very interesting way to use tags.
That would be great, too.
Thanks a lot!
This is not a scientific proof of anything, but when I upgraded from 0.55.6 to 0.56.1, hugo would not rebuild my website anymore.
I believe it was “my” fault because I was storing a file in the data folder that I was later reading with readfile. It is true that the documentation mentioned that only 3 file types are supported, and I was using something different. I was just reading the file and handling it myself which was totally fine with 0.55.6. So I am not sure why there is a restriction on the file types in the data folder, but clearly it started being enforced after 0.55.6 and it wasn’t with 0.55.6.
I speak for myself here, but hugo is quite big with a lot of non trivial concepts and it is hard to grasp them all. Although I have built and published my website with it, I definitely do not master all the concepts… Besides bugs of course, I think it is definitely a possibility that something will be broken because of lack of understanding…
1 Like
I have peculiar situation, my project depends heavily in code blocks and lists. The fault in this case is not on Hugo, but in blackfriday version in use. The releases after Hugo v0.55.4, uses a version of blackfriday that have some weird bugs related to lists and code blocks. Because of that I’m using only v0.55.4.
If you want to check yourself try, there is a bug open about it:
---
---
* level 1
```c
test
```
We had our site broken because one of the committers used a newer version of hugo which changed completely the way things were interpolated. The release notes did mention it though but we did not realize since one committer used a newer version by accident.
The release notes also mentioned how to fix it - just add
{{- $_hugo_config := `{ "version": 1 }` -}}
to the templates.
We check in the generated docs/ directory because we serve with github so now we closely watch the git diff to make sure there are no unexpected changes. This works well if committers pay attention to what actually changed - it would have caught this issue.