Add tool-versions file

[ThisIsMissEm]

This helps software like asdf discover exactly what version of hugo to use, since hugo versions often have incompatibilities.

I've been bitten many times working on docs but having the wrong version of hugo in my $PATH

[ThisIsMissEm]

Added comments to try to keep this in sync, since we can't reuse the tool-versions file in GitHub Actions directly

[ThisIsMissEm]

@ClearlyClaire the main reason I ended up using asdf for Hugo was because I contribute to multiple Hugo sites each running different incompatible versions, so I'd constantly get weird breakages when switching between repos. asdf helps with that by automatically switching my hugo version to the right one for the project & the .tool-versions file in the root of the repo acts as a bit of a guide as to what we use.

[mjankowski]

FYI, you can do something like...

echo ".tool-versions" >> .git/info/exclude

...which will let you get the benefits of asdf locally, w/out needing the project to adopt it or add to their gitignore.

[ThisIsMissEm]

I'd be of the inclination to suggest we do adopt .tool-versions here, not necessarily to say adopt asdf, but rather to have a file in the root of the repository that does contain the version required.

[mjankowski]

Yes, agreed on having it better locked/specified somewhere.

Im guessing theres no equivalent of .nvmrc or .ruby-version for hugo projects? Also, its too bad the format here with extended doesnt quite match the format needed in the CI config...

[ThisIsMissEm]

Also, its too bad the format here with extended doesnt quite match the format needed in the CI config...

Yeah, that annoys me too, but there isn't really anything we can do about that, unless we do an upstream PR to the github action to support .tool-versions syntax?

[mjankowski]

Sort of related - https://github.com/peaceiris/actions-hugo?tab=readme-ov-file#%EF%B8%8F-read-hugo-version-from-file - the GH action that publishes the site could pull that version value from a file (example there is a .env, but in theory could do whatever)

[github-actions[bot]]

This pull request has merge conflicts that must be resolved before it can be merged.

[mjankowski]

A tool-versions was added (maybe by accident?) as side effect of: https://github.com/mastodon/documentation/pull/1560

However, the thing that comment warned about has happened ... and there now is a disconnect between the github action version (0.140.2) and the tool-versions version (extended_0.130.0)

Want to rebase this to increase the tool-versions version (and leave the comment)?

Possible follow-up ... there are a bunch of releases since the version GH actions is using, could bump a bit.

[ThisIsMissEm]

@mjankowski an alternative way to do this is to actually parse the tool-versions file for the CI pipeline:

     - name: Setup Hugo Version
        id: hugo_version
        run: |
          HUGO_VERSION=$(cat .tool-versions | grep hugo | cut -d' ' -f2 | cut -d'_' -f2)
          echo "HUGO_VERSION=$HUGO_VERSION" >> "$GITHUB_ENV"

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

Which may be easier to maintain long-term. (I worked this out for the hachyderm/community website)

[ThisIsMissEm]

It'd probably actually be possible to write a small go program to convert from tool-versions to the environment variables: https://github.com/asdf-vm/asdf/blob/master/internal/toolversions/toolversions.go

[ThisIsMissEm]

But yeah, it's just an annoying thing that actions-hugo splits the extended out of the version.

[mjankowski]

Agreed that scripting would be nice, but at min we can sync them.

Similarly annoying, within .tool-versions, asdf uses a format like hugo extended_0.130.0, (keeping extended with the version) whereas mise (which uses tool-versions if it finds one) uses hugo-extended 0.142.0 style (keeps extended with package name and version separate)

[ThisIsMissEm]

Anyway, it's a relatively simple improvement that could be done to the hugo action: https://github.com/peaceiris/actions-hugo/issues/670

[mjankowski]

Going to close this because https://github.com/mastodon/documentation/pull/1762 bumped the hugo version, and added similar-ish comment to what was here.

Possible followup here would be some way to link those versions together, if we can do so simply and/or some more official way is supported by the actions, etc.