How to migrate from 6.4.x to 7.0.0?

[cagix]

Thank you very much for your great work on this theme. I've been using 6.4.1 up to now and after upgrading to 7.0.0 my previous archetypes no longer work, probably some other things are not working either. I see the indication of breaking changes in the release notes, but I can't really figure out what I need to adjust. Can you please provide guidance on what needs to be changed for the new version?

[McShelby]

I must admit that there are no clear advises just the hint to https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/designs/index.html in the release notes.

I've taken a peak in your repo and I think (haven't tested it) you have to change as follows:

• In the Front Matter of your pages, change the archetype front matter to type (value stays the same if you don't change your page design / archetype naming)
• move your files layouts/partials/archetypes/lecture-bc/article.html to layouts/lecture-bc/views/article.html

[cagix]

ah. i tested the first part (s/archetype/type/) ( to no avail), but missed the second part. thanks for pointing that out.

[cagix]

hmmm. there seems to be more. did also the second point, and now hugo is yelling at me. it searches just in the relearn-theme location, but not also in my "theme" where the archetypes are defined (as it did before). seems, my config needs some changes, too.

[cagix]

@McShelby so i copied all my archetypes into the main theme folder (i.e. the folder where relearn is 'installed'). now hugo does find my archetypes, and i get a lot of errors of this kind:

ERROR render of "section" failed: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/_default/list.html:5:5": execute of template failed: template: _default/list.html:5:5: executing "body" at <.Render>: error calling Render: failed to execute template _default/views/body.html: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/_default/views/body.html:1:4": execute of template failed: template: _default/views/body.html:1:4: executing "_default/views/body.html" at <partial "bodys/single.html" .>: error calling partial: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/partials/bodys/single.html:2:4": execute of template failed: template: partials/bodys/single.html:2:4: executing "partials/bodys/single.html" at <.Render>: error calling Render: "/pandoc/temp/01-lexing/antlr-lexing/_index.md:1:1": failed to execute template lecture-cg/views/article.html: "/usr/local/share/pandoc/hugo/hugo-theme-relearn/layouts/lecture-cg/views/article.html:1:13": execute of template failed: template: lecture-cg/views/article.html:1:13: executing "lecture-cg/views/article.html" at <.page>: can't evaluate field page in type *hugolib.pageState

something in the format of the archetypes seems to have changed, too?

[McShelby]

I'll take a look into it, this evening

Also, there may be some outcome for the docs.

[cagix]

No rush! I'm in the middle of term, and this might need some major adjustments on my side - I won't be able to address that for a few months.

[zeitgen]

I just gave up upgrading at all at some point, i guess it was 5.23.2.
Maybe it's just how Hugo works in general, but even following the guidelines and not modifying bundled templates doesn't help. Custom templates still rely on bundled, which get rewritten entirely.
For a non-developer, it's just too expensive to diff each theme file figuring out what's changed while your site is down.

[McShelby]

Personally I also prefer incremental upgrades.

In case you are far behind, it can be helpful to not upgrade to the latest version in one swoop but step by step to versions in between. This may end in a bit more work but can be easily be partioned in more digestable chunks.

The overall idea for many theme changes is to make everything configurable. So ideally you as a user would be in no need to touch any partials but solve any customization by configuration.

If you can not achieve your goals by configuration, feel free to post an issue.

[cagix]

But still, I tend to agree with @zeitgen. Particularly in the Hugo ecosystem, I've spent a frustrating amount of time over the years just to make the jump from one version to the next. There are simply too many variables in the game and both Hugo and the themes of course develop according to the ideas of the respective maintainers, and then my own customisations also enter the picture - it quickly takes a lot of time for me as a user to get my own project up and running again.

To be honest, I'm pondering whether and how I can remove some of the variables from the equation. At the moment, I need to keep four juggling balls in the air at the same time: Hugo, the theme, my customisations and, of course, my content together with the configuration. I am looking for a tool where I only have to maintain my content and where I don't have to worry about the rest. Docsify and LiaScript seem to be strong contenders, but they have serious shortcomings compared to the Relearn theme (given my use case). So, for now I'm stuck with Hugo+Relearn+customisations and need to check from version to version to discover which things stopped working this time.

[McShelby]

On the upside: I don't expect the themes structure to change that drastically in the future as with the past releases. It is now in a pretty good shape and complies to Hugo's best practices.

I agree, I have had my fair share adding to the upgrade pain with some clumsy implementation descisions in the first year of the fork. Those were finally removed with version 7.x. We all learn as we move along.

And for Docsify, LiaScript or any other solution: The gras is always greener on the other side. 😄

From 25+ years experience in software development I doubt that there are fewer hassle when upgrading those projects. They may only occur fewer times due to slower release cycles (which can be pretty fast paced with Hugo and the theme)

But don't get me wrong, I don't want to sound self-convinced. I hear you!

[cagix]

Don't get me wrong - your theme is awesome and you're doing a great job! For me it's mainly Hugo with a combination of being somewhat poorly documented and moving at great pace and me having lots of documents to maintain. Things tend to break too often in the release cycle.

[zeitgen]

I can only second @cagix: the theme is a lifesaver and literally gives me a job now =) and i'm happy we share some common ground here.
Given the theme gets more an more stable, i might try an opposite approach to upgrading: just throw in all the latest and greatest, and then rebuild my customizations on top of that.