Standardize standard-release naming conventions

[Spiker985]

Current:

As of right now, we currently have no standardized naming for artifacts for standard releases. We have used everything from ARM.Linux.Pulsar-1.101.0-beta-arm64.AppImage to Linux.pulsar-1.101.0-beta.tar.gz. Neither of which provide a very good foundation for downloading, for us - nor downstream consumers.

Every standard update must be accompanied with a website update to update the specific URLs for the standard downloads.

Proposed:

• Continue prefixing the tag with v, and then the version number i.e. v1.102.0
• Continue naming the release the same as the tag, i.e. v1.102.0
• Drop the version number from the artifact names i.e. Pulsar_<OS>_<Architecture>.<Extension>

Examples:

OS	Architecture	Artifact Name
Linux	x86 64	Pulsar_Linux_x86-64.tar.gz
Linux	ARM64	Pulsar_Linux_arm64.tar.gz
Apple	x86 64	Pulsar_Apple_x86-64.tar.gz
Apple	ARM64	Pulsar_Apple_arm64.tar.gz
Windows	Installer	Pulsar_Windows_Installer.exe
Windows	Portable	Pulsar_Windows_Portable.exe

This change would allow us to switch to using GitHub's special latest URLs for our downloads instead i.e. https://github.com/pulsar-edit/pulsar/releases/latest/download/Pulsar_Linux_arm64.AppImage.

This means no website updates to coincide with standard updates, and no deviation for downstream consumers - all urls will be standardized.

If a downstream consumer wants to reference a specific version, the URL changes slightly i.e. https://github.com/pulsar-edit/pulsar/releases/download/v1.102.0/Pulsar_Linux_arm64.AppImage.

Note the switch from releases/latest/download to releases/download/<tag>

Note:

• This would only affect standard releases. The rolling releases will still utilize our download microservice to query our CD/CI platform (Cirrus) for the most recent master branch, which completed successfully.
• The list of examples is not exhaustive and is only meant to give an idea for each OS.
• All windows releases are 64 bit, there are no 32 bit builds - hence we use the delimiter of Installer vs Portable instead.

[meadowsys]

hmm, a few notes/recommendations:

• is it stylised x86_64 or x86-64 (underscore or hyphen)? yeah this is a bit bikesheddy, but wanted to take this opportunity before it finalises and its difficult to change
• shouldn't we use macOS instead of Apple as the OS name?

Using macOS instead of Apple and keeping the hyphen x84-64, it would be:

Pulsar_Linux_x86-64.deb
Pulsar_Linux_x86-64.rpm
Pulsar_Linux_x86-64.AppImage
Pulsar_Linux_x86-64.tar.gz
Pulsar_Linux_arm64.deb
Pulsar_Linux_arm64.rpm
Pulsar_Linux_arm64.AppImage
Pulsar_Linux_arm64.tar.gz

Pulsar_macOS_x86-64.dmg
Pulsar_macOS_x86-64.zip
Pulsar_macOS_arm64.dmg
Pulsar_macOS_arm64.zip

Pulsar_Windows_Installer.exe
Pulsar_Windows_Portable.exe

[Spiker985]

I only went with Apple over macOS, because - actually, is there any way to install a dmg on an iPad or iPhone?

If not, I'd say go with macOS.
If so, I'd still probably go with macOS, because that is well out of our supported device range

[meadowsys]

I think I do like using just x64 for the simplicity? XD I'll create a new comment with this so it gets a bit more visibility

[meadowsys]

I only went with Apple over macOS, because - actually, is there any way to install a dmg on an iPad or iPhone?

Just saw this comment >< I think not, hah, but either way, yeah we don't support it, and we probably would have to create a seperate build for those?

[Daeraxa]

As much as it makes sense to me, I feel people might be confused over the whole x86 vs ARM for macOS thing. Most other native binaries I've seen do just say something like macOS and macOS (Apple Silicon) - VLC for example (well actually most don't bother and do universal binaries instead).

[meadowsys]

I think we can write a short sentence or so on the website, just above the table where the downloads are. I wonder if we can also create a universal binary for people who just don't know (of course we should probably prefer the non-universal version because universal can be up to double the size)

[meadowsys]

Officially proposing candidate number 2:

Pulsar-Linux-x64.deb
Pulsar-Linux-x64.rpm
Pulsar-Linux-x64.AppImage
Pulsar-Linux-x64.tar.gz
Pulsar-Linux-arm64.deb
Pulsar-Linux-arm64.rpm
Pulsar-Linux-arm64.AppImage
Pulsar-Linux-arm64.tar.gz

Pulsar-macOS-x64.dmg
Pulsar-macOS-x64.zip
Pulsar-macOS-arm64.dmg
Pulsar-macOS-arm64.zip

Pulsar-Windows-Installer.exe
Pulsar-Windows-Portable.exe

Pulsar-<OS>-<arch>.<ext>

• OS is one of Linux, macOS, or Windows
• for Linux and macOS, arch is one of x64 or arm64
• for Windows, arch is replaced by Installer or Portable since we only support 64bit

Tagging is the same as original proposal, consistently prefixing our version numbers with a v to get ex. v1.102.0

[DeeDeeG]

Looks like we are already in agreement about standardizing on just hyphens (or at least not a mix of hyphens and underscores! Not both!), and adding "Installer" to the Windows installer. 👍 I hadn't noticed we both did that independent of one-another.

And @Spiker985's comment at the top of the thread also adds "Installer" to the Windows installer, so that's 3/3 so far!

[DeeDeeG]

So one thing I remember about the intent of the original naming scheme was, it'd be alphabetized by the most actionable/user-relevant part, which is the platform name, first.

So you know if you're on Arm Linux, well then look for Arm.

The first fields were also unique per OS/Arch combo, so for Apple Silicon you'd notice "Silicon" and go, "oh, that's the one." Hence "Silicon", not "Arm", even though yeah, if Apple ever actually gets a monopoly on elemental silicon, lord help us.

All told, very optimized for visual skimming, which is what humans care about when browsing the dozen-plus files on the GitHub Releases page, anyhow.

As mentioned elsewhere, I am incorrigible digital hoarder and like having the version numbers in the binary names, so it's clear what they are in my Downloads folder. (And somewhat by convention from how Linux distros usually name their .debs/.rpms or what-have-you. If someone drops or copy-pastes a binary somewhere, it's clear enough what version it is.)

Just want to make the case for essentially the original naming scheme with whatever finer points bikeshedded properly.

But the key benefits of the original scheme, for quick reference are:

• Visual skimmability by humans when looking at them all together, such as on GitHub Releases
  • Good alphabetization
  • Unique prefixes

If we can keep that going, (or at least retain these strengths in whatever naming scheme we end up with) it might be worthwhile.

[Spiker985]

Well, I wonder if we could propose a new filename when offering it up to the client.

So like, from a website <-> GitHub standpoint, the artifact doesn't include the version. But when downloaded from our site, it can offer the filename as <Proposed Format>-<version>.<extension>

Then downstream people don't have to deal with it, especially for automated purposed, and data-hoarders like @DeeDeeG 😉 can have their cake and eat it too - if it is served up by our site 🤔

[meadowsys]

I do know there is the content-disposition header: content-disposition: attachment; filename="Pulsar-v1.102.0-macOS-arm64.dmg". I did propose using this before somewhere in discord, on the existing download microservice, but I think it wouldn't be as easy as sending a redirect (which my impression is that's what it does currently?), it would have to stream the download, which would balloon costs.

I guess if we do some clientside scriptery, it could store it into a blob, then download that blob? something like...

Actually! I was looking at old code to see what kinda clientside trickery I once did to give a custom name to a blob when downloading it, and I stumbled upon the download attribute on <a> tag, which I had used. This could be easy then! On our download page, we just link to the artifact on github with no version in the name, then on page load, we can query github's API for the latest version, construct filenames in the name (like Pulsar-${version}-macOS-arm64.dmg), get the <a> tags and set the download attributes (like a_element.download = that_expression_above). Then, on download, filenames will have versions in the name! If this is what we end up agreeing on, I may be able to PR this too, hehe.

[cat-master21]

If the version is the filename, then the tag name shoud match to be the same. For example tag name: v1.102.0 filename: Linux.v1.102.0.AppImage and not Linux.1.102.0.AppImage because for flatpak-manifest-checker, it expects the tag name (version) to be part of the filename, including the v.

[DeeDeeG]

@cat-master21 I was looking at that data validator, all of this can be worked around, their data checker thingy is extremely flexible, and I would volunteer to help with that at some point.

Making whatever we go with consumable by automated services like the flathub data validator thingy is definitely part of my thinking when participating in this discussion.

[cat-master21]

@cat-master21 I was looking at that data validator, all of this can be worked around, their data checker thingy is extremely flexible, and I would volunteer to help with that at some point.

Making whatever we go with consumable by automated services like the flathub data validator thingy is definitely part of my thinking when participating in this discussion.

Okay well if you want to help you can contribute at https://github.com/flathub/dev.pulsar_edit.Pulsar

[Daeraxa]

Another benefit to not having version numbers in the file name is that we can more easily distribute on Appimagehub. At the moment it links to https://github.com/pulsar-edit/pulsar/releases/download/v1.101.0-beta/Linux.Pulsar-1.101.0-beta.AppImage so would need a PR to update it. (It seems somebody made this at some point):
AppImage/appimage.github.io#3084
https://www.appimagehub.com/p/1982012
And honestly I don't see any reason to not support it.

[DeeDeeG]

Actually they expect to consume a standardized naming convention with the version numbers in it, per their README: https://github.com/AppImage/appimage.github.io#how-to-submit-appimages-to-the-catalog

Standard nomenclature:

• AppImage filename consists of pieces: Application name, hyphen, version, hypen, architecture, dot, AppImage suffix
• [ . . . ]
• Example: App-1.1-x86_64.AppImage in a repo called "App"

It looks to me like they will query our Releases page every so often if given just our GitHub repo URL and renew the metadata from the latest AppImage per new GitHub Release we put out, if we use their standard file naming.

EDIT: If they will keep querying a static URL to a specific AppImage file, then we can indeed use the static/evergreen "latest" AppImage direct URL if we don't include the version numbers in the filenames. We might want to ping the AppImage folks for clarity on this, maybe open an issue asking about it over at their "AppImage Directory" repo.

[Spiker985]

Proposal 3:
Artifact names are exactly as proposal 2

Pulsar-Linux-x64.deb
Pulsar-Linux-x64.rpm
Pulsar-Linux-x64.AppImage
Pulsar-Linux-x64.tar.gz
Pulsar-Linux-arm64.deb
Pulsar-Linux-arm64.rpm
Pulsar-Linux-arm64.AppImage
Pulsar-Linux-arm64.tar.gz

Pulsar-macOS-x64.dmg
Pulsar-macOS-x64.zip
Pulsar-macOS-arm64.dmg
Pulsar-macOS-arm64.zip

Pulsar-Windows-Installer.exe
Pulsar-Windows-Portable.exe

• Links will be formatted as https://github.com/pulsar-edit/pulsar/releases/latest/download/<artifact_name>.
  • For downstream consumers, a static version url is thus: https://github.com/pulsar-edit/pulsar/releases/download/<tag_name>/<artifact_name>
• We can periodically query the latest release https://api.github.com/repos/pulsar-edit/pulsar/releases/latest to get the tag_name.
  • When the tag_name has changed from the previous value, we can update the download attribute on the a tags to "serve up" the new filename.
  • We can probably query on page load - since it is presumably cheaper, faster, and might be able to be cached by the browser.
    • In fact, we only need to query once on page load, despite having 14 artifacts, they will all be part of the same release.

Example a tag:

<a download="Pulsar-v1.102.0-Windows-Installer.exe" href="https://github.com/pulsar-edit/pulsar/releases/latest/download/Pulsar-Windows-Installer.exe" target="_blank">Installer</a>

[DeeDeeG]

This is neat, and if the filenames have no versions in them, we don't need to query the API, the URLs for the latest release binaries will always be 100% fully static, same exact URL for the foreseeable future, hard-code it in the downloads page once, ship it, stable forever.

If we have versions in the filenames, then yeah, we can query the GitHub API. Either to get the version number (derived from the tag name) and construct the filenames with that version number, or to straight-up drill down into the JSON for the assets of the latest release and filter for the correct ones, for example the one whose name contains the substrings "ARM" and ".deb", to narrow down to each OS/Arch/Package format so we put each one in the right spot on the page.

Regardless of versions in the filenames: If we do want to offer older releases (ones other than "latest") for whatever reason, then we need to be aware of/include the version numbers at least once in each URL (for the tag name).

Note: This ended up covering exactly the same ground as my "ways of automating" comment chain below. Sorry, I don't want to fragment discussion too much... I might delete my separate comment chain below, to keep discussion in one spot. I dunno.

[DeeDeeG]

Okay, so the download= trick does not work cross-origin, and our origin is pulsar-edit.dev, whereas the targeted file is from github.com, so it does not work, in practice.

Docs: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes

Demo of it not working: https://deedeeg.github.io/download.html --> See the tiny un-styled "Installer" link under the infobox.

Wanted filename when downloading: Pulsar-v1.102.0-Windows-Installer.exe
Actual filename when downloading: Windows.Pulsar.Setup.1.100.0-beta.exe

[DeeDeeG]

So, to make sure this discussion can address automatability concerns, I want to go over all the technical ways we have available for grabbing the binaries from GitHub Releases in a machine-assisted or automated way. Since I already went over human factors, let's go over machine factors.

• Hard-coded/static or predictable URLs --> direct binary download (no API usage needed)
  • Versionless latest: https://github.com/pulsar-edit/pulsar/releases/latest/download/Pulsar-Windows-Installer.exe
    • This is the special case enabled by versionless binary filenames. Call it "versionless latest static" or "evergreen static" URLs?
  • Predictable version-specific: https://github.com/pulsar-edit/pulsar/releases/download/v1.199.0/Windows-Installer.1.199.0.exe
  • Predictable version-specific: https://github.com/pulsar-edit/pulsar/releases/download/v1.199.0/Windows-Installer.exe
    • (Same as above, but no version in filename)
• GitHub.com REST API "Releases" endpoint + scripting (JS) --> JSON, filter with scripting to get a specific binary URL
  • Example: Get the latest release info from the API, filter the JSON for a binary containing the substring Windows-Installer
  • Example: Get a specific tagged version (such as v1.199.0) from the API, filter the resulting JSON for a binary containing the substring Windows-Installer
    • For either of these examples, the version number being in the binary filename is pretty much no barrier to a scripter to filter for the desired binaries.
• GitHub.com GraphQL API???
  • I dunno how to use this, to be honest, and it requires authorization with a PAT or equivalent token. Not something I'm interested in really, but the option technically exists.

Notes (click to expand, kinda rednundant to the reply comment below, tho)

I would note that the only technical scenario enabled by version-free names would be the "evergreen"/"versionless static" latest URL for grabbing any of the particular binaries off our latest GitHub Release, as a fully static URL that never ever changes.

Once we stabilize our filenames, predicting static URLs with versions in the filenames is as simple as knowing what the desired release version number is, perhaps aided by a quick check of what the latest is from the GitHub.com REST API "Releases" endpoint?.

And more sophisticated API-based access already needs arbitrarily-capable scripting to be useful, so in a scripting context, the version number in the filename would be a quite trivial barrier to overcome, IMO.

[cat-master21]

I think you summarized it good, yeah adding the version number is sometimes problematic I also recommend adding a v to the begining of the filename if it has the version because the tag name/version has a v at the begining. I think just to make it easy (and make it easier for automaticly/workflow releases) just to upload one file without the version number.

[confused-Techie]

I don't feel strongly about the topic going on here. So will be happy with whatever the rest of the community decides. The only thing I'd like to note, is that from a data hoarders perspective having the files include the filename is helpful. To easily go back and find exact versions.

Although beyond that, it doesn't serve much use. And realistically very few popular applications do this, just is more common on open source projects. But otherwise feel free to ping for any scripting that needs to be done if anyone would like, or if we do eventually want to to put some responsibility onto the download endpoint, even if that's literally just to grab the latest version, and then build the URLs based on that.

[meadowsys]

I think I feel partial towards no version in github releases (for the "evergreen static" urls), and using the a tag download attribute and github REST API to provide a nice filename for the website (as stated here https://github.com/orgs/pulsar-edit/discussions/134#discussioncomment-5082721). However, I wouldn't mind having versions in the filenames either. I would vote for the same naming scheme as in that comment I linked earlier, adding the version to be the last component before file extension, as it is the same across binaries for a version and wouldn't serve any purpose for visual scanning.

Side note, has there been an official poll for this? if there was, I have missed it >~<

[Daeraxa]

Side note, has there been an official poll for this? if there was, I have missed it >~<

No, I think this discussion is what needs to take place in order to make a poll with reasonable options to pick from

[DeeDeeG]

Yeah I am starting to think it'll be poll time soon, I wanted to maybe discuss a little on Discord so things can be synchronous for a sec, but one way or another I think a poll might be good soon on "versions vs no versions". And then we can either be unanimous about the rest of the name strings or put that to another poll maybe, IDK. Will post about it on Discord soon if I don't forget.

EDIT: Posted to gauge ability to move forward on a consensus, on Discord here: https://discord.com/channels/992103415163396136/992103415163396139/1082092641077952643

[catscarlet]

Yeah I like the idea!
The filenames right now always feel like:

• "What am I looking at?"
• "Are these some prereq-installer packages? You know the filenames are started with a platform-prefix"
• "I'm using a Linux LTS but not the latest LTS, so do I need a prereq-installer? or not? Where to find the minimum requirement of this version?"
• "Why is there an appImage prereq-installer?"
• "Oh wait that's the main pulsar package...???"
• "So all of these are main pulsar packages???"