Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Dont show invalid sbt and scalajs versions #614

Merged
merged 10 commits into from
Apr 9, 2020

Conversation

adpi2
Copy link
Member

@adpi2 adpi2 commented Apr 2, 2020

This PR is deployed to https://index-dev.scala-lang.org

First commit

  • minor version is optional for parsing scalajs version (e.g. sjs1_2.12)
  • drop out invalid scalajs (< 0.6) and sbt versions from home page and filters

Second commit

  • refactor ScalaTarget as an ADT of cases ScalaJvm, ScalaJs, ScalaNative or SbtPlugin

Third commit

  • drop out invalid scalajs and sbt versions from result list

@adpi2 adpi2 requested a review from sjrd April 2, 2020 15:09
Copy link
Contributor

@sjrd sjrd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a few small suggestions, but other it looks good to me. Did you pre-deploy these changes so that we can test them?

@adpi2
Copy link
Member Author

adpi2 commented Apr 2, 2020

It is deployed to http://index-dev.scala-lang.org

@sjrd
Copy link
Contributor

sjrd commented Apr 2, 2020

It is deployed to http://index-dev.scala-lang.org

Thanks!

Looking at https://index-dev.scala-lang.org/search?q=*&scalaJsVersions=1, I suspect there might be something wrong. There are definitely a lot more than 9 libraries with support for Scala.js 1.x. cats-core, and cats in general, should be there, for example.

Also, could we display Scala.js 1 as 1.x rather than just 1. I don't know why, but just 1 feels unnatural. We could also display 0.6 as 0.6.x for symmetry, though for some reason seeing 0.6 doesn't bother nearly as much as 1.

@adpi2
Copy link
Member Author

adpi2 commented Apr 2, 2020

There is only 9 scala.js 1.x libraries because I have reindexed an old snapshot dating 2017. Reindexing the entire database will be much longer but I will try that in a few moments.

The scala.js version comes from the name of the artifact (e.g. cats-core_sjs0.6_2.12 or cats-core_sjs1_2.12). It may be confusing not to stick with this naming convention and show 1.x instead of 1, don't you think?

@sjrd
Copy link
Contributor

sjrd commented Apr 2, 2020

There is only 9 scala.js 1.x libraries because I have reindexed an old snapshot dating 2017. Reindexing the entire database will be much longer but I will try that in a few moments.

Hum, then that means that it is still indexing libraries for milestones/RCs of 1.0.0. We'd like those not to be indexed anymore, as it is not useful, and it is actually downright misleading to say that they support 1.x, because support for 1.0.0-Mx or 1.0.0-RCx does not guarantee support for 1.0.0+.

The scala.js version comes from the name of the artifact (e.g. cats-core_sjs0.6_2.12 or cats-core_sjs1_2.12). It may be confusing not to stick with this naming convention and show 1.x instead of 1, don't you think?

When we talk about Scala.js 1.x, we always talk about 1.x. Nobody writes Scala.js 1. It doesn't really matter what the encoding of artifacts is. What matters for display is how people talk about the version number. So IMO 1 is more confusing than 1.x.

@adpi2
Copy link
Member Author

adpi2 commented Apr 3, 2020

@sjrd you are right about the milestones and RCs of scala.js 1.0.0 being indexed.

I need clarification on this: what do we do with future milestones and RCs of scala.js 1.1? Do we include them in 1.x or do we separate them in a 1.1 version?

This issue is not specific to scala.js: see #526 for scala jvm. I'll treat them both here. And what about scala native? Should we display all versions from 0.1 to 0.4?

@adpi2
Copy link
Member Author

adpi2 commented Apr 3, 2020

Also, I am afraid that the reindexing of the entire database does not work. It has been stuck since yesterday 9pm. I have to work on that too before merging.

@sjrd
Copy link
Contributor

sjrd commented Apr 3, 2020

This issue is not specific to scala.js: see #526 for scala jvm. I'll treat them both here. And what about scala native? Should we display all versions from 0.1 to 0.4?

The general rule for me would be: only index a milestone or RC if it is the very latest available version. That means that:

  • For Scala/JVM: index no milestone nor RC, since the latest stable release is 2.13.1, and there are no M or RC that are > 2.13.1
  • For Scala.js: same reasoning; index no milestone nor RC
  • For Scala Native: index 0.4.0-M2, since it is the latest available version (do not index 0.4.0-M1, assuming that even exists, since 0.4.0-M2 is more recent)

This general rule seems to work well for all the cases I can think of.

In addition to that, for stable releases, only index the following versions IMO:

  • Scala/JVM >= 2.10
  • Scala.js >= 0.6
  • Scala Native >= 0.3

I need clarification on this: what do we do with future milestones and RCs of scala.js 1.1? Do we include them in 1.x or do we separate them in a 1.1 version?

If the binary version is different, the ecosystem is different, so you must consider that a separate version. If the binary version is the same (e.g., Scala.js 1.1.0 will also use the binary version 1), then it is the same ecosystem, and they must in the same 1.x.

All you need to care about is the binary version. This is the source of truth. That is true for the JVM, for JS, for Native and for sbt. No exception.

@adpi2
Copy link
Member Author

adpi2 commented Apr 3, 2020

I am not clear about the meaning of "binary" in "binary version". Does it mean "binary compatibility"?

As far as I know, the rules of "binary compatibility" are not the same in Scala JVM and Scala.js, since 2.12 and 2.13 are not compatible but scala.js 1.0 and 1.1 should be compatible, right? It's even more complicated than that because sjs 0.5 is not compatible with sjs 0.6 and sjs 1.0.0-M2 is not compatible with 1.0.0.

@sjrd
Copy link
Contributor

sjrd commented Apr 3, 2020

When you parse the artifact names, all you ever get is the binary version. When you see _2.13, the binary version is 2.13. When you see _2.13.0-RC1, the binary version is 2.13.0-RC1. It's the same for Scala.js: when you see _sjs0.6, the binary version is 0.6. _sjs1 means 1. _sjs1.0-RC2 means 1.0-RC2.

So in Scaladex all you ever see is the binary version, since you cannot determine the full version (you can't tell from _2.13 whether it was built with 2.13.0 or 2.13.1). So as far as Scaladex is concerned, binary version = version.

And as soon as two binary versions are different, they create entirely different and incompatible ecosystems. So Scaladex should never try to be "smart" and collate together "similar" versions. No, if Scaladex sees two different (even if "similar") versions, they really are different, and must never be lumped together in the same bag.

@adpi2
Copy link
Member Author

adpi2 commented Apr 3, 2020

Alright then.

I like your point of view. Scaladex used to truncate binary version 2.12.3 to 2.12 but it makes things complicated. Your proposal is more predictable, I think. Yet, we should not display those weird 2.12.3 binary versions that do not conform to the norm. Agreed ?

@sjrd
Copy link
Contributor

sjrd commented Apr 3, 2020

The only reason you'd see a binary version like 2.12.3 is if the artifact is a compiler plugin. Otherwise the binary version would already be 2.12. 2.12.3 is not a "valid" binary version for non-compiler-plugin libraries.

How to deal with compiler plugins, I am not sure. My hunch is that you can just not index them. They are often accompanied by a genuine library anyway or by an sbt plugin, so that would be their entry point in Scaladex. For compiler plugins that are really just compiler plugins (and I can't name one off the top of my head), they would not be indexed, but I think that's fine for now. We can reconsider later if we need to find a solution for them.

So concretely, you can ignore "invalid" binary versions. Valid binary versions are:

  • JVM: x.y, x.y.z-Mw, x.y.z-RCw
  • JS: 0.y, x, x.y-Mw, x.y-RCw
  • Native: 0.y, x.y.z-Mw, x.y.z-RCw
  • sbt: x.y

@adpi2
Copy link
Member Author

adpi2 commented Apr 3, 2020

One more precision: so far every artifact is indexed even if it's target type is considered obsolete or invalid. I will keep it that way for the moment.

My goal is to discard invalid versions from the front page, the result list and the dropdown list of a project.

@adpi2
Copy link
Member Author

adpi2 commented Apr 3, 2020

Are you sure about JS x.y-Mw and x.y-RCw ? I would rather expect x.y.z-Mw and x.y.z-RCw.

@sjrd
Copy link
Contributor

sjrd commented Apr 3, 2020

Yes, I'm sure ;) It is initially computed here, which, for a pre-release version, delegates to binaryEmitted, which is defined here.

@adpi2 adpi2 force-pushed the 608-invalid-sbt-and-js-versions branch 3 times, most recently from d764563 to 7949a4d Compare April 6, 2020 13:33
@adpi2 adpi2 force-pushed the 608-invalid-sbt-and-js-versions branch from 7949a4d to a04a5f1 Compare April 6, 2020 13:35
@adpi2
Copy link
Member Author

adpi2 commented Apr 6, 2020

Here it comes ==> https://index-dev.scala-lang.org/

@adpi2 adpi2 requested a review from sjrd April 6, 2020 16:16
@adpi2 adpi2 linked an issue Apr 6, 2020 that may be closed by this pull request
@adpi2 adpi2 force-pushed the 608-invalid-sbt-and-js-versions branch from 654af25 to 5a53709 Compare April 9, 2020 07:34
@adpi2 adpi2 force-pushed the 608-invalid-sbt-and-js-versions branch from 5a53709 to e882e10 Compare April 9, 2020 07:58
@adpi2 adpi2 merged commit 8512902 into scalacenter:master Apr 9, 2020
@adpi2 adpi2 deleted the 608-invalid-sbt-and-js-versions branch April 9, 2020 08:18
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
Only push 1 commit if doing a feature branch release

Fix output of job so we can get the release_type

Updating a tag requires force-pushing, and that feels bad

Comment on PR when a preview release is published

Remove troublesome backticks that confuse bash...

Ideally we would be generating a markdown message with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

### Problems with backticks

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
Only push 1 commit if doing a feature branch release

Fix output of job so we can get the release_type

Updating a tag requires force-pushing, and that feels bad

Comment on PR when a preview release is published

Remove troublesome backticks that confuse bash...

Ideally we would be generating a markdown message with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

### Problems with backticks

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
Only push 1 commit if doing a feature branch release

Fix output of job so we can get the release_type

Updating a tag requires force-pushing, and that feels bad

Comment on PR when a preview release is published

Remove troublesome backticks that confuse bash...

Ideally we would be generating a markdown message with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

### Problems with backticks

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
Only push 1 commit if doing a feature branch release

Fix output of job so we can get the release_type

Updating a tag requires force-pushing, and that feels bad

Comment on PR when a preview release is published

Remove troublesome backticks that confuse bash...

Ideally we would be generating a markdown message with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

### Problems with backticks

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
This addresses #10,
providing support for publishing *preview* releases based off feature branches, ie PRs.

The UX of doing a preview release is very similar to the existing process for doing a full
release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md),
with only these differences:

* The developer needs to select the PR branch before clicking the green `Run workflow` button
* The version number will be the **upcoming** version number, but with a suffix that clearly
  indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`.
  Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT`
  releases.
* No branches are updated by the release (ie, not the PR's feature branch, and not the
  default `main` branch) - the preview release commit exists as its own tagged commit,
  taking the latest PR commit as its parent.
* GitHub release notes will not be created, but instead the PR using that branch will be
  updated with a comment providing details of the new release (version number, etc).

Internally, these 'preview release' changes take place if a non-default branch (ie a feature
branch, not `main`) is used:

* The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH`
* Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the
  single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed
  by the full release process (incrementing the version number and adding the `-SNAPSHOT`
  suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW`
  version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR.
* When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the
  _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command
  to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable
  branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation
  message including the hashes of all artifact files generated by the release, and at the point
  when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use
  a new, different, disposable, Git tag instead.

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters

## Problems with backticks

Ideally we would be generating a markdown message for the PR comment with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

...so for the time being this PR avoids them in the generated PR comment.
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
This addresses #10,
providing support for publishing *preview* releases based off feature branches, ie PRs.

The UX of doing a preview release is very similar to the existing process for doing a full
release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md),
with only these differences:

* The developer needs to select the PR branch before clicking the green `Run workflow` button
* The version number will be the **upcoming** version number, but with a suffix that clearly
  indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`.
  Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT`
  releases.
* No branches are updated by the release (ie, not the PR's feature branch, and not the
  default `main` branch) - the preview release commit exists as its own tagged commit,
  taking the latest PR commit as its parent.
* GitHub release notes will not be created, but instead the PR using that branch will be
  updated with a comment providing details of the new release (version number, etc).

Internally, these 'preview release' changes take place if a non-default branch (ie a feature
branch, not `main`) is used:

* The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH`
* Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the
  single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed
  by the full release process (incrementing the version number and adding the `-SNAPSHOT`
  suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW`
  version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR.
* When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the
  _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command
  to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable
  branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation
  message including the hashes of all artifact files generated by the release, and at the point
  when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use
  a new, different, disposable, Git tag instead.

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters

## Problems with backticks

Ideally we would be generating a markdown message for the PR comment with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

...so for the time being this PR avoids them in the generated PR comment.
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
This addresses #10,
providing support for publishing *preview* releases based off feature branches, ie PRs.

The UX of doing a preview release is very similar to the existing process for doing a full
release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md),
with only these differences:

* The developer needs to select the PR branch before clicking the green `Run workflow` button
* The version number will be the **upcoming** version number, but with a suffix that clearly
  indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`.
  Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT`
  releases.
* No branches are updated by the release (ie, not the PR's feature branch, and not the
  default `main` branch) - the preview release commit exists as its own tagged commit,
  taking the latest PR commit as its parent.
* GitHub release notes will not be created, but instead the PR using that branch will be
  updated with a comment providing details of the new release (version number, etc).

Internally, these 'preview release' changes take place if a non-default branch (ie a feature
branch, not `main`) is used:

* The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH`
* Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the
  single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed
  by the full release process (incrementing the version number and adding the `-SNAPSHOT`
  suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW`
  version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR.
* When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the
  _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command
  to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable
  branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation
  message including the hashes of all artifact files generated by the release, and at the point
  when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use
  a new, different, disposable, Git tag instead.

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters

## Problems with backticks

Ideally we would be generating a markdown message for the PR comment with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

...so for the time being this PR avoids them in the generated PR comment.
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
This addresses #10,
providing support for publishing *preview* releases based off feature branches, ie PRs.

The UX of doing a preview release is very similar to the existing process for doing a full
release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md),
with only these differences:

* The developer needs to select the PR branch before clicking the green `Run workflow` button
* The version number will be the **upcoming** version number, but with a suffix that clearly
  indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`.
  Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT`
  releases.
* No branches are updated by the release (ie, not the PR's feature branch, and not the
  default `main` branch) - the preview release commit exists as its own tagged commit,
  taking the latest PR commit as its parent.
* GitHub release notes will not be created, but instead the PR using that branch will be
  updated with a comment providing details of the new release (version number, etc).

Internally, these 'preview release' changes take place if a non-default branch (ie a feature
branch, not `main`) is used:

* The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH`
* Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the
  single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed
  by the full release process (incrementing the version number and adding the `-SNAPSHOT`
  suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW`
  version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR.
* When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the
  _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command
  to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable
  branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation
  message including the hashes of all artifact files generated by the release, and at the point
  when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use
  a new, different, disposable, Git tag instead.

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters

## Problems with backticks

Ideally we would be generating a markdown message for the PR comment with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

...so for the time being this PR avoids them in the generated PR comment.
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
This addresses #10,
providing support for publishing *preview* releases based off feature branches, ie PRs.

The UX of doing a preview release is very similar to the existing process for doing a full
release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md),
with only these differences:

* The developer needs to select the PR branch before clicking the green `Run workflow` button
* The version number will be the **upcoming** version number, but with a suffix that clearly
  indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`.
  Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT`
  releases.
* No branches are updated by the release (ie, not the PR's feature branch, and not the
  default `main` branch) - the preview release commit exists as its own tagged commit,
  taking the latest PR commit as its parent.
* GitHub release notes will not be created, but instead the PR using that branch will be
  updated with a comment providing details of the new release (version number, etc).

Internally, these 'preview release' changes take place if a non-default branch (ie a feature
branch, not `main`) is used:

* The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH`
* Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the
  single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed
  by the full release process (incrementing the version number and adding the `-SNAPSHOT`
  suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW`
  version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR.
* When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the
  _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command
  to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable
  branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation
  message including the hashes of all artifact files generated by the release, and at the point
  when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use
  a new, different, disposable, Git tag instead.

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters

## Problems with backticks

Ideally we would be generating a markdown message for the PR comment with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

...so for the time being this PR avoids them in the generated PR comment.
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
This addresses #10,
providing support for publishing *preview* releases based off feature branches, ie PRs.

The UX of doing a preview release is very similar to the existing process for doing a full
release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md),
with only these differences:

* The developer needs to select the PR branch before clicking the green `Run workflow` button
* The version number will be the **upcoming** version number, but with a suffix that clearly
  indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`.
  Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT`
  releases.
* No branches are updated by the release (ie, not the PR's feature branch, and not the
  default `main` branch) - the preview release commit exists as its own tagged commit,
  taking the latest PR commit as its parent.
* GitHub release notes will not be created, but instead the PR using that branch will be
  updated with a comment providing details of the new release (version number, etc).

Internally, these 'preview release' changes take place if a non-default branch (ie a feature
branch, not `main`) is used:

* The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH`
* Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the
  single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed
  by the full release process (incrementing the version number and adding the `-SNAPSHOT`
  suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW`
  version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR.
* When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the
  _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command
  to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable
  branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation
  message including the hashes of all artifact files generated by the release, and at the point
  when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use
  a new, different, disposable, Git tag instead.

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters

## Problems with backticks

Ideally we would be generating a markdown message for the PR comment with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

...so for the time being this PR avoids them in the generated PR comment.
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
This addresses #10,
providing support for publishing *preview* releases based off feature branches, ie PRs.

The UX of doing a preview release is very similar to the existing process for doing a full
release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md),
with only these differences:

* The developer needs to select the PR branch before clicking the green `Run workflow` button
* The version number will be the **upcoming** version number, but with a suffix that clearly
  indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`.
  Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT`
  releases.
* No branches are updated by the release (ie, not the PR's feature branch, and not the
  default `main` branch) - the preview release commit exists as its own tagged commit,
  taking the latest PR commit as its parent.
* GitHub release notes will not be created, but instead the PR using that branch will be
  updated with a comment providing details of the new release (version number, etc).

Internally, these 'preview release' changes take place if a non-default branch (ie a feature
branch, not `main`) is used:

* The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH`
* Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the
  single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed
  by the full release process (incrementing the version number and adding the `-SNAPSHOT`
  suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW`
  version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR.
* When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the
  _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command
  to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable
  branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation
  message including the hashes of all artifact files generated by the release, and at the point
  when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use
  a new, different, disposable, Git tag instead.

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters

## Problems with backticks

Ideally we would be generating a markdown message for the PR comment with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

...so for the time being this PR avoids them in the generated PR comment.
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
This addresses #10,
providing support for publishing *preview* releases based off feature branches, ie PRs.

The UX of doing a preview release is very similar to the existing process for doing a full
release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md),
with only these differences:

* The developer needs to select the PR branch before clicking the green `Run workflow` button
* The version number will be the **upcoming** version number, but with a suffix that clearly
  indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`.
  Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT`
  releases.
* No branches are updated by the release (ie, not the PR's feature branch, and not the
  default `main` branch) - the preview release commit exists as its own tagged commit,
  taking the latest PR commit as its parent.
* GitHub release notes will not be created, but instead the PR using that branch will be
  updated with a comment providing details of the new release (version number, etc).

Internally, these 'preview release' changes take place if a non-default branch (ie a feature
branch, not `main`) is used:

* The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH`
* Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the
  single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed
  by the full release process (incrementing the version number and adding the `-SNAPSHOT`
  suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW`
  version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR.
* When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the
  _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command
  to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable
  branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation
  message including the hashes of all artifact files generated by the release, and at the point
  when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use
  a new, different, disposable, Git tag instead.

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters

## Problems with backticks

Ideally we would be generating a markdown message for the PR comment with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

...so for the time being this PR avoids them in the generated PR comment.
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
This addresses #10,
providing support for publishing *preview* releases based off feature branches, ie PRs.

The UX of doing a preview release is very similar to the existing process for doing a full
release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md),
with only these differences:

* The developer needs to select the PR branch before clicking the green `Run workflow` button
* The version number will be the **upcoming** version number, but with a suffix that clearly
  indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`.
  Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT`
  releases.
* No branches are updated by the release (ie, not the PR's feature branch, and not the
  default `main` branch) - the preview release commit exists as its own tagged commit,
  taking the latest PR commit as its parent.
* GitHub release notes will not be created, but instead the PR using that branch will be
  updated with a comment providing details of the new release (version number, etc).

Internally, these 'preview release' changes take place if a non-default branch (ie a feature
branch, not `main`) is used:

* The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH`
* Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the
  single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed
  by the full release process (incrementing the version number and adding the `-SNAPSHOT`
  suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW`
  version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR.
* When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the
  _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command
  to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable
  branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation
  message including the hashes of all artifact files generated by the release, and at the point
  when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use
  a new, different, disposable, Git tag instead.

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters

## Problems with backticks

Ideally we would be generating a markdown message for the PR comment with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

...so for the time being this PR avoids them in the generated PR comment.
rtyley added a commit to guardian/gha-scala-library-release-workflow that referenced this pull request Jan 4, 2024
This addresses #10,
providing support for publishing *preview* releases based off feature branches, ie PRs.

The UX of doing a preview release is very similar to the existing process for doing a full
release (https://github.com/guardian/gha-scala-library-release-workflow/blob/main/docs/making-a-release.md),
with only these differences:

* The developer needs to select the PR branch before clicking the green `Run workflow` button
* The version number will be the **upcoming** version number, but with a suffix that clearly
  indicates this is a preview release, eg: `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4`.
  Note that this is _not_ a `-SNAPSHOT` release, the workflow does not support `SNAPSHOT`
  releases.
* No branches are updated by the release (ie, not the PR's feature branch, and not the
  default `main` branch) - the preview release commit exists as its own tagged commit,
  taking the latest PR commit as its parent.
* GitHub release notes will not be created, but instead the PR using that branch will be
  updated with a comment providing details of the new release (version number, etc).

Internally, these 'preview release' changes take place if a non-default branch (ie a feature
branch, not `main`) is used:

* The `🔒 Init` job `release_type` output is `PREVIEW_FEATURE_BRANCH` rather than `FULL_MAIN_BRANCH`
* Only 1 commit is pushed by the workflow, rather than 2, and _not_ onto the branch - the
  single commit exists as a tagged leaf to the side of the PR branch. The 2nd commit normally needed
  by the full release process (incrementing the version number and adding the `-SNAPSHOT`
  suffix) is not needed for preview releases - there are already enough details in the `-PREVIEW`
  version-suffix to keep preview releases unique, even if you do many releases for 1 commit in 1 PR.
* When that 1 commit is pushed, it's initially pushed with a _disposable_ Git tag - not the
  _release_ tag. Pushing _any_ commit requires either a branch or tag for the `git push` command
  to work on (you can't just push a commit id - I've tried), and there is no pre-existing suitable
  branch (we don't want to modify the PR feature branch) or tag (the release tag has an annotation
  message including the hashes of all artifact files generated by the release, and at the point
  when the commit is pushed, those artifacts & their hashes are not available yet), so we have to use
  a new, different, disposable, Git tag instead.

## Choice of version-suffix for preview releases

https://semver.org/#spec-item-9 says:

> 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-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.
>
> 10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD.

### How can we prevent tooling from thinking our preview releases are stable releases?

If we're not using the `-SNAPSHOT` suffix, there's a risk that tooling will assume that our preview releases are stable releases, and attempt to auto-upgrade to them.

* IntelliJ automatically suggests dependency upgrades - it uses `PackageVersionNormalizer` with specific stability tokens that include 'preview'
* Scala Steward raises dependency upgrade PRs - it uses `isPreRelease` which recognises `Hash` (6+ or 8 hex chars) & specific `Alpha` components that include 'preview'. See also scala-steward-org/scala-steward#1033, scala-steward-org/scala-steward#1549 etc
* Scaladex uses PreRelease.scala - scalacenter/scaladex#614

Consequently, to be certain of being recognised as a pre-release, it seems wise to include these components in the version number:

* 'PREVIEW'
* a commit hash of at least 8 characters

### NPM version numbers...

Some Guardian libraries are released simultaneously for both Scala and other platforms like NPM
(for instance, `content-api-models`, see guardian/content-api-models#229).
Both NPM and sbt/Maven work well with simple three-number semver version numbers, but how well will
NPM handle extended version number like `1.0.7-PREVIEW.feature1.2024-01-04T1230.42ed11d4` ?

### 'PREVIEW', 'BETA', 'ALPHA', or...?

Justin points out the 'PREVIEW' has a particular meaning for the Content Pipeline team ('Preview' vs 'Live'
content) - could potentially cause some confusion there.

I initially chose 'PREVIEW' (from the identifiers that IntelliJ & Scala Steward understand) partially
because both 'BETA' & 'ALPHA' imply some meaning about the stage of development in the software release
cycle that may or may not be appropriate - it's not obvious which one truly reflects what we're doing
when we make an early release from a PR, and it's annoying to have to choose. Additionally, looking at
the Wikipedia article that describes the different stages - the label 'pre-alpha' might even be more
appropriate: https://en.wikipedia.org/wiki/Software_release_life_cycle

## Problems with backticks

Ideally we would be generating a markdown message for the PR comment with lots of backticks
for styling:

https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

...like this:

rtyley/sample-project-using-gha-scala-library-release-workflow#1 (comment)

...but they get interpreted by BASH, and cause trouble...

https://github.com/rtyley/sample-project-using-gha-scala-library-release-workflow/actions/runs/7399435634/job/20130944058

...so for the time being this PR avoids them in the generated PR comment.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
3 participants