build: change release asset names

[ee7]

Currently, the release assets are named:

configlet-linux-64bit.tgz
configlet-mac-64bit.tgz
configlet-windows-64bit.zip

See: configlet releases and .github/bin/create-artifact.

But this doesn't allow #24 very neatly. If we add arm64 then just 64bit is not enough, and 64bit-arm is a bad suffix in my opinion (because arm alone is the usual way to refer to the 32-bit ARM architecture, and 64bit isn't explicitly x86-64).

A similar problem occurred in exercism/cli - see exercism/cli#700 (comment).

Some possible improvements:

• Use amd64 or x86-64 instead of 64bit
• Use macOS instead of mac
• Include the configlet version in the asset name

In the long-term, I'd suggest something like:

configlet_4.1.0_checksums_sha256.txt
configlet_4.1.0_checksums_sha256.txt.minisig
configlet_4.1.0_FreeBSD_amd64.tar.gz
configlet_4.1.0_FreeBSD_arm64.tar.gz
configlet_4.1.0_Linux_amd64.tar.gz
configlet_4.1.0_Linux_arm.tar.gz
configlet_4.1.0_Linux_arm64.tar.gz
configlet_4.1.0_Linux_i386.tar.gz
configlet_4.1.0_Linux_powerpc64.tar.gz
configlet_4.1.0_Linux_riscv64.tar.gz
configlet_4.1.0_macOS_amd64.tar.gz
configlet_4.1.0_macOS_arm64.tar.gz
configlet_4.1.0_OpenBSD_amd64.tar.gz
configlet_4.1.0_OpenBSD_arm64.tar.gz
configlet_4.1.0_Windows_amd64.zip
configlet_4.1.0_Windows_i386.zip

This has a few things that I don't necessarily expect to release for, just to illustrate.

This would also require changes to the fetch-configlet scripts.

We can also consider:

• Adding _musl to the linux asset names.
• Using .tar.gz instead of .tgz
• Using .tar.xz
• Using zstd
• The choice between x86-64, x86_64, amd64, and x64
• The choice between arm64, and aarch64
• The choice between i386, i686, 386, x86, and x32
• The choice between darwin, macos, and macOS

For inspiration, we can look how bigger projects name their release assets.

Assorted examples:

• https://github.com/cli/cli/releases/tag/v2.20.0-pre0
• https://github.com/superfly/flyctl/releases/tag/v0.0.428-pre-1
• https://github.com/arduino/arduino-cli/releases/tag/0.28.0-rc.1
• https://github.com/datreeio/datree/releases/tag/1.7.1
• https://github.com/goreleaser/nfpm/releases/tag/v2.21.0
• https://github.com/lindell/multi-gitter/releases/tag/v0.43.1
• https://github.com/0xPolygon/polygon-edge/releases/tag/v0.6.1
• https://github.com/scaleway/scaleway-cli/releases/tag/v2.6.2
• https://github.com/tendermint/tendermint/releases/tag/v0.37.0-rc1
• https://github.com/twitchdev/twitch-cli/releases/tag/v1.1.12
• https://github.com/UpCloudLtd/upcloud-cli/releases/tag/v2.2.0
• https://github.com/vultr/vultr-cli/releases/tag/v2.15.0
• https://ziglang.org/download/0.10.0/release-notes.html#Tier-2-Support
• https://ziglang.org/download/
• https://man.sr.ht/builds.sr.ht/compatibility.md
• https://github.com/BurntSushi/ripgrep/releases
• https://github.com/VSCodium/vscodium/releases
• https://github.com/syncthing/syncthing/releases
• https://github.com/gohugoio/hugo/releases
• https://github.com/electron/electron/releases
• https://github.com/etcd-io/etcd/releases
• https://github.com/golangci/golangci-lint/releases
• https://github.com/helm/helm/releases
• https://github.com/hetznercloud/cli/releases
• https://github.com/kubernetes/minikube/releases
• https://github.com/kubernetes/kops/releases
• https://github.com/llvm/llvm-project/releases/tag/llvmorg-14.0.0
• https://github.com/ory/hydra/releases
• https://github.com/jedisct1/piknik/releases
• https://github.com/junegunn/fzf/releases
• https://github.com/restic/restic/releases
• https://github.com/rclone/rclone/releases
• https://github.com/sharkdp/bat/releases
• https://github.com/status-im/nimbus-eth2/releases

See also:

• https://nim-lang.org/docs/compiler/platform.html#CPU
• https://wiki.osdev.org/Target_Triplet
• https://clang.llvm.org/docs/CrossCompilation.html#target-triple
• https://llvm.org/doxygen/classllvm_1_1Triple.html
• https://git.savannah.gnu.org/cgit/config.git/tree/config.guess

[ee7]

I was wondering what the label property of a release asset was. It turns out that it controls the name of the asset on the release page. It seems that very few GitHub repos use it, but see:

• https://github.com/github/hub/releases/tag/v2.14.2
• https://cli.github.com/manual/gh_release_upload
• https://docs.github.com/en/rest/reference/releases#update-a-release-asset

This might be worth considering when deciding on the new asset naming format.

---

gh --repo github/hub release view v2.14.2 --json assets | jq '[.assets[] | {label:.label, name}]'

(label is a reserved keyword in jq, so we can't use the shortcut {label, name}).

[
  {
    "label": "hub 2.14.2 for macOS",
    "name": "hub-darwin-amd64-2.14.2.tgz"
  },
  {
    "label": "hub 2.14.2 for FreeBSD 32-bit",
    "name": "hub-freebsd-386-2.14.2.tgz"
  },
  {
    "label": "hub 2.14.2 for FreeBSD 64-bit",
    "name": "hub-freebsd-amd64-2.14.2.tgz"
  },
  {
    "label": "hub 2.14.2 for Linux 32-bit",
    "name": "hub-linux-386-2.14.2.tgz"
  },
  {
    "label": "hub 2.14.2 for Linux 64-bit",
    "name": "hub-linux-amd64-2.14.2.tgz"
  },
  {
    "label": "hub 2.14.2 for Linux ARM 32-bit",
    "name": "hub-linux-arm-2.14.2.tgz"
  },
  {
    "label": "hub 2.14.2 for Linux ARM 64-bit",
    "name": "hub-linux-arm64-2.14.2.tgz"
  },
  {
    "label": "hub 2.14.2 for Windows 32-bit",
    "name": "hub-windows-386-2.14.2.zip"
  },
  {
    "label": "hub 2.14.2 for Windows 64-bit",
    "name": "hub-windows-amd64-2.14.2.zip"
  }
]

[ErikSchierboom]

In the long-term, I'd suggest something like:
[...]

I quite like the look of that list, except for the mixed casing. Instead of macOS and FreeBSD, I think I would prefer macos and freebsd.

This would also require changes to the fetch-configlet scripts.

Indeed. I can batch-script those. Luckily, we only need to change one file to fix the configlet workflow: https://github.com/exercism/github-actions/blob/main/configlet-ci/fetch-configlet

I was wondering what the label property of a release asset was. It turns out that it controls the name of the asset on the release page. It seems that very few GitHub repos use it, but see:

Ooh, that's nice!

[ee7]

I quite like the look of that list, except for the mixed casing. Instead of macOS and FreeBSD, I think I would prefer macos and freebsd.

OK. How about this?

configlet_4.1.0_checksums_sha256.txt
configlet_4.1.0_checksums_sha256.txt.minisig
configlet_4.1.0_freebsd_arm64.tar.gz
configlet_4.1.0_freebsd_x86-64.tar.gz
configlet_4.1.0_linux_arm.tar.gz
configlet_4.1.0_linux_arm64.tar.gz
configlet_4.1.0_linux_i386.tar.gz
configlet_4.1.0_linux_powerpc64.tar.gz
configlet_4.1.0_linux_riscv64.tar.gz
configlet_4.1.0_linux_x86-64.tar.gz
configlet_4.1.0_macos_arm64.tar.gz
configlet_4.1.0_macos_x86-64.tar.gz
configlet_4.1.0_openbsd_arm64.tar.gz
configlet_4.1.0_openbsd_x86-64.tar.gz
configlet_4.1.0_windows_arm64.zip
configlet_4.1.0_windows_i386.zip
configlet_4.1.0_windows_x86-64.zip

Where the rationale is:

• It's good to put configlet at the start, both to help the user, and in case we ever start adding a differently named program to the releases.
• It's good to include the version string. A script that downloads a release asset can match the pattern, rather than hard-coding the asset name.
• Given that we want to include the version string, it's better to delimit with underscores rather than hyphens because semantic versions can contain hyphens. That is:
  • some-app_1.0.0-beta.1_linux_x86-64.tar.gz is better than
  • some_app-1.0.0-beta.1-linux-x86_64.tar.gz because splitting by - does not tokenize: the -beta part of the version is awkward
• It's better to put release number directly after configlet, so that common information in filenames is in the same location
• It's better to put operating system before architecture, because sorting by operating system is probably easier to scan - people think more about what operating system they're on
• macos is more widely undestood than darwin, and more correct/common than mac. macOS is Apple's official capitalization, but macos is the casing in target triples, and lowercasing everywhere keeps things simple
• arm64 is more widely understood than aarch64
• x86-64 may be more widely understood than x64 and amd64, and the lattermost looks too similar to arm64
• i386 avoids potential confusion between x86 and x86-64
• powerpc64 is more descriptive than ppc64
• .zip for Windows and .tar.gz otherwise is better than .zip for everything, or .tar.gz for everything
• .tar.gz is more intuitive than .tgz - it's a tarball, which is then compressed
• .zip for Windows and .tar.gz otherwise is also consistent with the source code archives that GitHub automatically adds to every release
• .minisig is more obvious than .sig
• Releasing hashes and signatures is better than just hashes or just signatures, and doing so by using one checksum file and its minisig file is less noisy than having a signature file for each asset, or both a signature file and hash file for each asset.
• Information like musl, gnu and msvc isn't important right now, because we're statically linking on Linux, and compiling+testing on Windows when possible is better than cross-compiling for Windows. And I don't foresee a reason for us to release both statically linked and dynamically linked builds for the same OS and architecture.
• We don't need to release e.g. .deb, .rpm, .AppImage, .dmg, .apk, an .exe installer, or .msi
• .tar.xz or .tar.zst aren't worth it, because the decrease in file size (or possibly extraction time) isn't important, and because some systems don't have them installed (e.g. a fresh install of OpenBSD doesn't include xz)
• It is less likely that a configlet user wants to run it on an operating system like netbsd, dragonfly, and solaris
• It is less likely that a configlet user wants to run it on an architecture like mips64, or s390x

I haven't thought too hard about the 32-bit arm names.

[ErikSchierboom]

LGTM