build: change release asset names #363

ee7 · 2021-06-18T07:32:30Z

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:

See also:

The text was updated successfully, but these errors were encountered:

ee7 · 2022-04-12T16:14:54Z

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:

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 · 2022-04-13T08:56:01Z

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 · 2022-10-26T19:10:45Z

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 · 2022-10-27T14:08:34Z

LGTM

Before this commit, the release assets were named like: configlet-linux-64bit.tgz configlet-mac-64bit.tgz configlet-windows-64bit.zip configlet_4.0.0-beta.7_checksums_sha256.txt With this commit, the next release will have assets named: configlet_4.0.0-beta.8_checksums_sha256.txt configlet_4.0.0-beta.8_linux_x86-64.tar.gz configlet_4.0.0-beta.8_macos_x86-64.tar.gz configlet_4.0.0-beta.8_windows_x86-64.zip Where we: - Make the archive naming format match that of the checksums file - Add a version string - Delimit with an underscore, not a hyphen - Rename `64bit` to `x86-64` - Rename `32bit` to `i386` - Rename `tgz` to `tar.gz` - Rename `mac` to `macos` So far, we have only released configlet for x86-64, and the release assets have always had an ambiguous `64bit` in the names. This naming format was old (added by d4c6e26, 2020-10-09), and was ultimately inherited from: - the `exercism/configlet-v2` releases [1] - the `exercism/cli` releases [2][3] However, we're getting closer to adding releases for other 64-bit architectures, so it's especially important to change the names now. The rationale for the particular use of underscores and hyphens is: - We want to have the version string in the asset filenames - Configlet uses version strings that are compatible with the Semantic Versioning spec - It is more common to use hyphens in executable names than underscores - The Semantic Versioning spec forbids using an underscore, and specifies that prerelease versions can use hyphens [4]: Section 9: A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. [...] Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92 That is, there's an argument for the format of: some-app_1.0.0-beta.1_linux_x86-64.tar.gz rather than: some_app-1.0.0-beta.1-linux-x86_64.tar.gz because `_` fully separates the components of the first, and `-` does not separate the components of the second (due to the `-beta` part of the version string). This does ignore the convention of `_` as an inter-word space, however. [1] https://github.com/exercism/v2-configlet/releases [2] exercism/cli#700 (comment) [3] https://github.com/exercism/cli/releases/tag/v3.0.12 [4] https://semver.org/ Closes: #363 Refs: #24

Before this commit, the release assets were named like: configlet-linux-64bit.tgz configlet-mac-64bit.tgz configlet-windows-64bit.zip configlet_4.0.0-beta.7_checksums_sha256.txt With this commit, the next release will have assets named: configlet_4.0.0-beta.8_checksums_sha256.txt configlet_4.0.0-beta.8_linux_x86-64.tar.gz configlet_4.0.0-beta.8_macos_x86-64.tar.gz configlet_4.0.0-beta.8_windows_x86-64.zip Where we: - Make the archive naming format match that of the checksums file - Add a version string - Delimit with an underscore, not a hyphen - Rename `64bit` to `x86-64` - Rename `32bit` to `i386` - Rename `tgz` to `tar.gz` - Rename `mac` to `macos` So far, we have only released configlet for x86-64, and the release assets have always had an ambiguous `64bit` in the names. This naming format was old (added by d4c6e26836a5, 2020-10-09), and was ultimately inherited from: - the `exercism/configlet-v2` releases [1] - the `exercism/cli` releases [2][3] However, we're getting closer to adding releases for other 64-bit architectures, so it's especially important to change the names now. The rationale for the particular use of underscores and hyphens is: - We want to have the version string in the asset filenames - Configlet uses version strings that are compatible with the Semantic Versioning spec - It is more common to use hyphens in executable names than underscores - The Semantic Versioning spec forbids using an underscore, and specifies that prerelease versions can use hyphens [4]: Section 9: A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. [...] Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92 That is, there's an argument for the format of: some-app_1.0.0-beta.1_linux_x86-64.tar.gz rather than: some_app-1.0.0-beta.1-linux-x86_64.tar.gz because `_` fully separates the components of the first, and `-` does not separate the components of the second (due to the `-beta` part of the version string). This does ignore the convention of `_` as an inter-word space, however. [1] https://github.com/exercism/v2-configlet/releases [2] exercism/cli#700 (comment) [3] https://github.com/exercism/cli/releases/tag/v3.0.12 [4] https://semver.org/ Closes: exercism/configlet#363 Refs: exercism/configlet#24 exercism/configlet#705

Before this commit, the release assets were named like: configlet-linux-64bit.tgz configlet-mac-64bit.tgz configlet-windows-64bit.zip configlet_4.0.0-beta.7_checksums_sha256.txt With this commit, the next release will have assets named: configlet_4.0.0-beta.8_checksums_sha256.txt configlet_4.0.0-beta.8_linux_x86-64.tar.gz configlet_4.0.0-beta.8_macos_x86-64.tar.gz configlet_4.0.0-beta.8_windows_x86-64.zip Where we: - Make the archive naming format match that of the checksums file - Add a version string - Delimit with an underscore, not a hyphen - Rename `64bit` to `x86-64` - Rename `32bit` to `i386` - Rename `tgz` to `tar.gz` - Rename `mac` to `macos` So far, we have only released configlet for x86-64, and the release assets have always had an ambiguous `64bit` in the names. This naming format was old (added by d4c6e26836a5, 2020-10-09), and was ultimately inherited from: - the `exercism/configlet-v2` releases [1] - the `exercism/cli` releases [2][3] However, we're getting closer to adding releases for other 64-bit architectures, so it's especially important to change the names now. The rationale for the particular use of underscores and hyphens is: - We want to have the version string in the asset filenames - Configlet uses version strings that are compatible with the Semantic Versioning spec - It is more common to use hyphens in executable names than underscores - The Semantic Versioning spec forbids using an underscore, and specifies that prerelease versions can use hyphens [4]: Section 9: A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. [...] Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92 That is, there's an argument for the format of: some-app_1.0.0-beta.1_linux_x86-64.tar.gz rather than: some_app-1.0.0-beta.1-linux-x86_64.tar.gz because `_` fully separates the components of the first, and `-` does not separate the components of the second (due to the `-beta` part of the version string). This does ignore the convention of `_` as an inter-word space, however. [1] https://github.com/exercism/v2-configlet/releases [2] exercism/cli#700 (comment) [3] https://github.com/exercism/cli/releases/tag/v3.0.12 [4] https://semver.org/ exercism/configlet#363 exercism/configlet#24 exercism/configlet#705

ee7 added the kind: build Non-.nim changes that affect the release binary label Jun 18, 2021

ee7 mentioned this issue Oct 22, 2021

build: bump Nim from 1.4.8 to 1.6.0 #419

Merged

ee7 mentioned this issue Apr 12, 2022

build: upload checksums file #552

Merged

ee7 added this to Configlet roadmap Jul 1, 2022

ee7 mentioned this issue Nov 5, 2022

.github, fetch-configlet: rename release assets #705

Merged

ee7 closed this as completed in #705 Nov 11, 2022

ee7 moved this to Done in Configlet roadmap Nov 11, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

build: change release asset names #363

build: change release asset names #363

ee7 commented Jun 18, 2021 •

edited

Loading

ee7 commented Apr 12, 2022 •

edited

Loading

ErikSchierboom commented Apr 13, 2022

ee7 commented Oct 26, 2022 •

edited

Loading

ErikSchierboom commented Oct 27, 2022

build: change release asset names #363

build: change release asset names #363

Comments

ee7 commented Jun 18, 2021 • edited Loading

ee7 commented Apr 12, 2022 • edited Loading

ErikSchierboom commented Apr 13, 2022

ee7 commented Oct 26, 2022 • edited Loading

ErikSchierboom commented Oct 27, 2022

ee7 commented Jun 18, 2021 •

edited

Loading

ee7 commented Apr 12, 2022 •

edited

Loading

ee7 commented Oct 26, 2022 •

edited

Loading