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.

Sign up for GitHub

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

Jump to bottom

Adopt GHA Scala Library Release Workflow #299

Merged
merged 1 commit into from
Dec 13, 2023
Merged

Adopt GHA Scala Library Release Workflow #299

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
name: Release

on:
workflow_dispatch:

jobs:
release:
uses: guardian/gha-scala-library-release-workflow/.github/workflows/reusable-release.yml@main
permissions:
contents: write
secrets:
AUTOMATED_MAVEN_RELEASE_PGP_SECRET: ${{ secrets.AUTOMATED_MAVEN_RELEASE_PGP_SECRET }}
AUTOMATED_MAVEN_RELEASE_SONATYPE_PASSWORD: ${{ secrets.AUTOMATED_MAVEN_RELEASE_SONATYPE_PASSWORD }}
Comment on lines +12 to +13
Copy link
Member Author

Choose a reason for hiding this comment

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

These GitHub Organisation Secrets will be granted to this repo by https://github.com/guardian/github-secret-access/pull/21.

23 changes: 8 additions & 15 deletions README.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Facia Scala Client [![fapi-client-play28 Scala version support](https://index.scala-lang.org/guardian/facia-scala-client/fapi-client-play28/latest-by-scala-version.svg)](https://index.scala-lang.org/guardian/facia-scala-client/fapi-client-play28)
Facia Scala Client [![fapi-client-play28 Scala version support](https://index.scala-lang.org/guardian/facia-scala-client/fapi-client-play28/latest-by-scala-version.svg)](https://index.scala-lang.org/guardian/facia-scala-client/fapi-client-play28) [![Release](https://github.com/guardian/facia-scala-client/actions/workflows/release.yml/badge.svg)](https://github.com/guardian/facia-scala-client/actions/workflows/release.yml)
==================

Facia's Scala client is split into two parts.
Expand Down Expand Up @@ -79,20 +79,13 @@ At the time of writing, Tools, CAPI, Dotcom, Mobile teams (Mapi) and Ophan all u

## Building a release

[This document](https://docs.google.com/document/d/1rNXjoZDqZMsQblOVXPAIIOMWuwUKe3KzTCttuqS7AcY/edit) is a good source of information about releasing Guardian artefacts generally.
This project uses the [`gha-scala-library-release-workflow`](https://github.com/guardian/gha-scala-library-release-workflow)
to release to Maven Central. To release a new version, execute the
[Release](https://github.com/guardian/facia-scala-client/actions/workflows/release.yml)
workflow in the Actions tab on GitHub:

To release a new version of the client:
![RunReleaseWorkflow](https://github.com/guardian/facia-scala-client/assets/52038/23920a58-80c6-4e6d-b5bc-6f58bf78f41d)

1. Ensure you have a GPG key listed on a public key server.
2. Ensure you are registered on Sonatype for Guardian projects.
3. Open sbt and run the [sbt release](https://github.com/sbt/sbt-release) task:
_You'll need to refresh the page to see the new workflow run._

```
$ sbt
sbt:facia-api-client> release
```

4. When the release process has completed successfully, document the new version with a GitHub Release note
([guide](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository))
describing the change (the `Generate release notes` button can give you a good start!):
https://github.com/guardian/facia-scala-client/releases/new
https://github.com/guardian/facia-scala-client/assets/52038/dfc014d9-98f9-4d20-8977-0a20340083d1
33 changes: 5 additions & 28 deletions build.sbt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import Dependencies._
import sbtrelease.ReleaseStateTransformations._
import sbtversionpolicy.withsbtrelease.ReleaseVersion.fromAggregatedAssessedCompatibilityWithLatestRelease

organization := "com.gu"

Expand All @@ -8,41 +9,18 @@ name := "facia-api-client"
description := "Scala client for The Guardian's Facia JSON API"

val sonatypeReleaseSettings = Seq(
licenses := Seq("Apache V2" -> url("http://www.apache.org/licenses/LICENSE-2.0.html")),
scmInfo := Some(ScmInfo(
url("https://github.com/guardian/facia-scala-client"),
"scm:git:git@github.com:guardian/facia-scala-client.git"
)),
pomExtra := (
<url>https://github.com/guardian/facia-scala-client</url>
<developers>
<developer>
<id>janua</id>
<name>Francis Carr</name>
<url>https://github.com/janua</url>
</developer>
<developer>
<id>adamnfish</id>
<name>Adam Fisher</name>
<url>https://github.com/adamnfish</url>
</developer>
</developers>
),
Comment on lines -12 to -30
Copy link
Member Author

Choose a reason for hiding this comment

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

All the required metadata deleted here is now provided by gha-scala-library-release-workflow (quite concisely, thanks to sbt-sonatype's GitHubHosting helper!).

licenses := Seq("Apache V2" -> url("https://www.apache.org/licenses/LICENSE-2.0.html")),
releaseVersion := fromAggregatedAssessedCompatibilityWithLatestRelease().value,
Copy link
Member Author

Choose a reason for hiding this comment

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

fromAggregatedAssessedCompatibilityWithLatestRelease() will intelligently set the release version based on sbt-version-policy's compatibility assessment, thanks to scalacenter/sbt-version-policy#187 - so a 'major', 'minor' or 'patch' version number bump, according to Scala's recommended semver guidelines.

This means that sbt 1.5.0 and above will be able to tell when incompatible versions of this library are being used in a project.

releaseCrossBuild := true, // true if you cross-build the project for multiple Scala versions
releaseProcess := Seq[ReleaseStep](
checkSnapshotDependencies,
inquireVersions,
runClean,
runTest,
Copy link
Member Author

Choose a reason for hiding this comment

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

This is a bit unusual, the other 3 repos that that have adopted gha-scala-library-release-workflow haven't needed to drop this line, but the unit tests in this project, facia-scala-client, require special credentials (see #272) and passing them through in a generic way to gha-scala-library-release-workflow is a bit tricky.

I have a couple of ideas on how to solve this, but would like to address it in a subsequent PR.

setReleaseVersion,
commitReleaseVersion,
tagRelease,
// For non cross-build projects, use releaseStepCommand("publishSigned")
releaseStepCommandAndRemaining("+publishSigned"),
releaseStepCommand("sonatypeBundleRelease"),
Comment on lines -41 to -42
Copy link
Member Author

@rtyley rtyley Dec 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

For projects using gha-scala-library-release-workflow, the 'sign' & 'release' steps are taken care of by the workflow, rather than by the sbt-release plugin, so that the necessary credentials can be isolated from the library build/test process.

This means we can remove publishSigned & sonatypeBundleRelease here.

setNextVersion,
commitNextVersion,
pushChanges
Copy link
Member Author

Choose a reason for hiding this comment

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

For projects using gha-scala-library-release-workflow, the 'push' step is taken care of by the workflow, rather than by the sbt-release plugin, so that the library build/test process does not need to be given 'write' access to the repository.

commitNextVersion
)
)

Expand All @@ -52,7 +30,6 @@ lazy val root = (project in file(".")).aggregate(
fapiClient_play27,
fapiClient_play28
).settings(
publishArtifact := false,
publish / skip := true,
Comment on lines -55 to 33
Copy link
Member Author

Choose a reason for hiding this comment

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

publishArtifact := false is unnecessary when publish / skip := true is set.

publish / skip is the recommended key for this purpose, and is the key examined by sbt-version-policy when it checks to see if it can skip calculating compatibility for a particular subproject.

sonatypeReleaseSettings
)
Expand All @@ -70,12 +47,12 @@ def baseProject(module: String, majorMinorVersion: String) = Project(s"$module-p
scalaVersion := "2.13.11",
crossScalaVersions := Seq(scalaVersion.value, "2.12.18"),
scalacOptions := Seq(
"-release:11",
Copy link
Member Author

Choose a reason for hiding this comment

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

gha-scala-library-release-workflow is currently using Java 17 for compiling everything, so it's important to specify that you want Java 11-compatible bytecode if you're going to be using this library in projects running Java 11.

"-feature",
"-deprecation",
"-Xfatal-warnings"
),
libraryDependencies += scalaTest,
publishTo := sonatypePublishToBundle.value,
Copy link
Member Author

Choose a reason for hiding this comment

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

gha-scala-library-release-workflow will set publishTo to the appropriate value (as it happens, a local-filesystem staging repository), no need to set it here.

sonatypeReleaseSettings
)

Expand Down
2 changes: 1 addition & 1 deletion project/build.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
sbt.version=1.9.3
sbt.version=1.9.7
3 changes: 1 addition & 2 deletions project/plugins.sbt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
addSbtPlugin("com.github.sbt" % "sbt-release" % "1.1.0")

addSbtPlugin("com.github.sbt" % "sbt-pgp" % "2.2.1")
addSbtPlugin("ch.epfl.scala" % "sbt-version-policy" % "3.2.0")
Copy link
Member Author

@rtyley rtyley Dec 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

We don't need the sbt-pgp plugin, as gha-scala-library-release-workflow will sign the artifacts directly using GPG... but we do need sbt-version-policy, to intelligently work out the correct version number based on compatibility with the latest release:

releaseVersion := fromAggregatedAssessedCompatibilityWithLatestRelease().value

Note also that our project automatically has versionScheme set to early-semver by sbt-version-policy - this is the only versionScheme currently supported by sbt-version-policy.


addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "3.9.21")

Loading