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

Adopt GHA Scala Library Release Workflow #416

Merged
merged 1 commit into from
Dec 5, 2023

Conversation

rtyley
Copy link
Member

@rtyley rtyley commented Dec 5, 2023

This is the second library (after etag-caching), to adopt guardian/gha-scala-library-release-workflow . This is a new automated library release process, which means that a new library release can be published to Maven Central with the click of a button:

image

This replaces the old release process which had developers manually running sbt release on their own laptops - each developer had to obtain their own PGP key and Sonatype credentials, which was an elaborate setup process. Now, there is one single set of credentials, available through GitHub Organisation Secrets, like we already do with NPM.

Required changes

The changes required to adopt the automated workflow:

  • No need to set sonatypeProfileName or ThisBuild / publishTo, that's now done by the workflow.
  • Remove the sign, publish, release & push steps of sbt-release's releaseProcess configuration, because the workflow does those now, and the workflow only wants sbt release to create the versioning commits, and tag them appropriately. The workflow does the rest itself.
  • Remove sbt-pgp plugin because it's no longer used - the workflow does the signing using gpg directly.
  • GitHub administration: Grant this repo (play-secret-rotation) access to these two GitHub Organisation Secrets (probably requires Organisation Owner privileges):

Additionally, we add automatic version numbering based on compatibility assessment performed by sbt-version-policy:

  • Add the sbt-version-policy plugin, to allow it to do the compatibility assessment. This also sets the versionScheme for this library to early-semver, which is the recommended versioning for Scala libraries, and sbt-version-policy and correct sbt-eviction-issue-detection pretty much depend on the versionScheme being early-semver. Thus we also need to switch to using a new semver version number for our library version!
  • Add the releaseVersion := fromAggregatedAssessedCompatibilityWithLatestRelease().value sbt setting, which will intelligently set the release version based on sbt-version-policy's compatibility assessment, thanks to Simplify integration with sbt-release scalacenter/sbt-version-policy#187 .
  • Use publish / skip := true, rather than other hacks like publish := {} or publishArtifact := false, to tell sbt not to publish modules that we don't want published (typically, the 'root' module) - this is important because sbt-version-policy won't understand those hacks, but will understand publish / skip := true means that it doesn't need to assess compatibility there.

@rtyley rtyley requested a review from a team as a code owner December 5, 2023 12:55
@rtyley rtyley force-pushed the adopt-GHA-Scala-Library-Release-Workflow branch 2 times, most recently from 7a333e7 to 0345b7f Compare December 5, 2023 13:07
This is the second library, after https://github.com/guardian/etag-caching, to adopt
https://github.com/guardian/gha-scala-library-release-workflow/blob/main/README.md .

The changes required to adopt the automated workflow:

* No need to set `sonatypeProfileName` or `ThisBuild / publishTo`,
  that's now done by the workflow.
* Remove the sign, publish, release & push steps of sbt-release's `releaseProcess`
  configuration, because the workflow does those now, and the workflow only
  wants `sbt release` to create the versioning commits, and tag them appropriately.
  The workflow does the rest itself.
* Remove `sbt-pgp` plugin because it's no longer used - the workflow does the signing
  using `gpg` directly.

Additionally, we add **automatic version numbering** based on compatibility assessment
performed by `sbt-version-policy`:

* Add the `sbt-version-policy` plugin, to allow it to do the compatibility assessment.
  This also sets the `versionScheme` for this library to `early-semver`, which is
  the recommended versioning for Scala libraries, and `sbt-version-policy` and
  correct sbt-eviction-issue-detection pretty much depend on the `versionScheme`
  being `early-semver`. Thus we also need to switch to using a new semver version
  number for our library version!
* Add the `releaseVersion := fromAggregatedAssessedCompatibilityWithLatestRelease().value`
  sbt setting, which will intelligently set the release version based on `sbt-version-policy`'s
  compatibility assessment, thanks to scalacenter/sbt-version-policy#187 .
* Use `publish / skip := true`, rather than other hacks like `publish := {}` or
  `publishArtifact := false`, to tell sbt not to publish modules that we don't want published
  (typically, the 'root' module) - this is important because `sbt-version-policy` won't
  understand those hacks, but _will_ understand `publish / skip := true` means that it doesn't
  need to assess compatibility there.
@rtyley rtyley force-pushed the adopt-GHA-Scala-Library-Release-Workflow branch from 0345b7f to 058d62a Compare December 5, 2023 13:09
@@ -1 +1 @@
ThisBuild / version := "0.41-SNAPSHOT"
ThisBuild / version := "1.0.0-SNAPSHOT"

Choose a reason for hiding this comment

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

Are we saying that, when we merge this change, we can run the release workflow and it will build/deploy version 1.0.0? I suppose this means that, in the case where we're using this new plugin, the version.sbt file is the source of truth for the next version?

Copy link

@DavidLawes DavidLawes Dec 5, 2023

Choose a reason for hiding this comment

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

Also, I created this project, should I be updating it to use this new plugin? (it's configured with my own sonatype username and password at the moment....)

Copy link
Member Author

Choose a reason for hiding this comment

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

we can run the release workflow and it will build/deploy version 1.0.0? I suppose this means that, in the case where we're using this new plugin, the version.sbt file is the source of truth for the next version?

That's right! Actually, I don't think that's a change from the existing behaviour for version numbers - the workflow hasn't changed things here. You can think of '-SNAPSHOT' as meaning '-SNAPSHOT-PREVIEW', so 1.0.0-SNAPSHOT is actually a 'preview' release of 1.0.0 before it's actually finished and released. This is standard Maven release versioning - we always work with the version number set to a snapshot of what the next release will be.

I created this project, should I be updating it to use this new plugin? (it's configured with my own sonatype username and password at the moment....)

Well, at the moment, gha-scala-library-release-workflow is in an early-feedback phase - I'd like it tried out on just a small number of repositories, so people can give me feedback to incorporate before we update all the Scala library repos at the Guardian!

If you'd like to try out updating https://github.com/guardian/mobile-apps-api-models to work with the new flow, that would be absolutely wonderful, you'd be being an awesome beta-tester!

Choose a reason for hiding this comment

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

Thanks for the explanation - in the mapi-models project I discarded the use of version.sbt (in favour of the user defining this via the github release UI) so it's good to see how the release process can integrate with this file (which is a mechanism that feels neater).

Copy link
Member Author

Choose a reason for hiding this comment

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

Yeah, it's an interesting choice to make, whether to initiate by creating a GitHub release, which is beautiful and elegant, but requires there to already be a tag, with some random human-chosen version number, or to initiate by running the workflow with workflow-dispatch, which is not quite as beautiful, but doesn't require there to be an already-existing tag... I've gone with the second one!

Copy link

@DavidLawes DavidLawes left a comment

Choose a reason for hiding this comment

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

Good to know we have org-wide secrets for maven releases now!

@rtyley
Copy link
Member Author

rtyley commented Dec 5, 2023

Good to know we have org-wide secrets for maven releases now!

Yeah! Though those credentials should only be used with gha-scala-library-release-workflow, and not other setups which have less isolation between executing library code and the credentials!

@rtyley rtyley merged commit 19064e7 into main Dec 5, 2023
2 checks passed
@rtyley
Copy link
Member Author

rtyley commented Dec 5, 2023

This did successfully do a release for this library!

image

However, it took a few attempts, because of two things I'd forgotten were also required:

rtyley added a commit to guardian/play-googleauth that referenced this pull request Dec 7, 2023
This is the 3rd library to adopt https://github.com/guardian/gha-scala-library-release-workflow,
a new automated library release process that allows releases to be
published to Maven Central with the click of a button.

The changes in here are similar to the ones in
guardian/play-secret-rotation#416, with the addition
that sbt settings that provide the pom metadata required by Maven Central
( https://central.sonatype.org/publish/requirements/#project-name-description-and-url )
can be simplified thanks to the functionality provided by
xerial/sbt-sonatype#58 - setting
`sonatypeProjectHosting` takes care of a lot the fields!
emdash-ie added a commit to guardian/marley that referenced this pull request Dec 14, 2023
Following [the example from
play-secret-rotation](guardian/play-secret-rotation#416),
rather than set up a new developer credential to release the next
version of this library, this commit sets up
[guardian/gha-scala-library-release-workflow](https://github.com/guardian/gha-scala-library-release-workflow).
emdash-ie added a commit to guardian/marley that referenced this pull request Dec 14, 2023
Following [the example from
play-secret-rotation](guardian/play-secret-rotation#416),
rather than set up a new developer credential to release the next
version of this library, this commit sets up
[guardian/gha-scala-library-release-workflow](https://github.com/guardian/gha-scala-library-release-workflow).
emdash-ie added a commit to guardian/marley that referenced this pull request Dec 18, 2023
- Adopt scala library release GHA workflow

  Following [the example from
  play-secret-rotation](guardian/play-secret-rotation#416),
  rather than set up a new developer credential to release the next
  version of this library, this commit sets up
  [guardian/gha-scala-library-release-workflow](https://github.com/guardian/gha-scala-library-release-workflow).

- Further `gha-scala-library-release-workflow` tweaks

  Further to
  #102 (comment),
  these are a few more tweaks:

  * Delete the entire `sonatype.sbt` file that was providing these keys
    that `gha-scala-library-release-workflow` now takes care of for us:
    * `sonatypeProfileName` - see https://github.com/guardian/gha-scala-library-release-workflow/blob/7d278d4d44e30b4b4c0f6791053bdeb40b8159cb/.github/workflows/reusable-release.yml#L258
    * `publishTo` - see guardian/facia-scala-client#299 (comment)
    * `scmInfo` & `pomExtra` - see guardian/facia-scala-client#299 (review)
    * `homepage` - https://github.com/xerial/sbt-sonatype/blob/da75ed2efe29e7d674a6d6af5103b4aa1cecefb8/src/main/scala/xerial/sbt/Sonatype.scala#L368
  * Specify Java 11-compatible bytecode - see https://github.com/guardian/facia-scala-client/pull/299/files#r1425630691

  As part of some of these changes, I've also removed the vestiges of
  the build-configuration that adapted the build for Scala 2.11 &
  2.12 (eg the `versionDependent()` helper method) - these are no longer
  need since #78 removed support
  for Scala 2.12 in January 2023.

Co-authored-by: Roberto Tyley <roberto.tyley@gmail.com>
emdash-ie added a commit to guardian/marley that referenced this pull request Dec 18, 2023
- Adopt scala library release GHA workflow

  Following [the example from
  play-secret-rotation](guardian/play-secret-rotation#416),
  rather than set up a new developer credential to release the next
  version of this library, this commit sets up
  [guardian/gha-scala-library-release-workflow](https://github.com/guardian/gha-scala-library-release-workflow).

- Further `gha-scala-library-release-workflow` tweaks

  Further to
  #102 (comment),
  these are a few more tweaks:

  * Delete the entire `sonatype.sbt` file that was providing these keys
    that `gha-scala-library-release-workflow` now takes care of for us:
    * `sonatypeProfileName` - see https://github.com/guardian/gha-scala-library-release-workflow/blob/7d278d4d44e30b4b4c0f6791053bdeb40b8159cb/.github/workflows/reusable-release.yml#L258
    * `publishTo` - see guardian/facia-scala-client#299 (comment)
    * `scmInfo` & `pomExtra` - see guardian/facia-scala-client#299 (review)
    * `homepage` - https://github.com/xerial/sbt-sonatype/blob/da75ed2efe29e7d674a6d6af5103b4aa1cecefb8/src/main/scala/xerial/sbt/Sonatype.scala#L368
  * Specify Java 11-compatible bytecode - see https://github.com/guardian/facia-scala-client/pull/299/files#r1425630691

  As part of some of these changes, I've also removed the vestiges of
  the build-configuration that adapted the build for Scala 2.11 &
  2.12 (eg the `versionDependent()` helper method) - these are no longer
  need since #78 removed support
  for Scala 2.12 in January 2023.

Co-authored-by: Roberto Tyley <roberto.tyley@gmail.com>
@rtyley rtyley deleted the adopt-GHA-Scala-Library-Release-Workflow branch April 3, 2024 16:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants