Only consider versions with pre-release identifiers as pre-releases #1033
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This change allows updates from e.g. 8.0.192-R14 to 12.0.2-R18 (where the 'R' stands for Release). It is currently not allowed because the hyphen in the version number makes it a pre-release version and we don't allow updates to a pre-release of a different version series. With this change we require that the version acually contains a pre-release identifier like RC, SNAPSHOT, or alpha to be considered a pre-release version.
Codecov Report
@@ Coverage Diff @@
## master #1033 +/- ##
==========================================
+ Coverage 69.09% 69.18% +0.09%
==========================================
Files 88 88
Lines 1346 1350 +4
Branches 44 44
==========================================
+ Hits 930 934 +4
Misses 416 416
Continue to review full report at Codecov.
|
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
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This change allows updates from e.g. 8.0.192-R14 to 12.0.2-R18 (where
the 'R' stands for Release). It is currently not allowed because the
hyphen in the version number makes it a pre-release version and we
don't allow updates to a pre-release of a different version series.
With this change we require that the version acually contains a
pre-release identifier like RC, SNAPSHOT, or alpha to be considered a
pre-release version.