Add release notes URLs to your POMs

Tooling
1

TLDR: Scala Steward will now link to release notes in its pull requests if the POM of the new version contains a info.releaseNotesUrl property that contains a URL of the release notes.

Scala Steward is using project.scm.url and project.url of the POM to add links to the repositories of the dependencies it is updating and it also tries to find release notes, changelogs, and version diffs based on the repository URL. This works quite well for dependencies that use GitHub and put their release notes on GitHub. An example PR that demonstrates this is Update cats-effect to 3.4.4 by scala-steward · Pull Request #2865 · scala-steward-org/scala-steward · GitHub.

If a dependency puts its release notes somewhere where it cannot be derived from the repository URL, there was no way for Scala Steward to include a link to them in its PRs. This is why we recently changed Scala Steward to read the info.releaseNotesUrl property from the POM and use that to link to the release notes. This new property allows library maintainers to put their release notes anywhere they want to and allows Scala Steward and other tools (Scaladex for example) to retrieve release notes in a generic way.

If you want to include the release notes into your POM, here is how it can be done with sbt and Mill:

sbt:

projectID ~= { id =>
  val releaseNotesUrl =
    "info.releaseNotesUrl" -> "https://www.scala-lang.org/blog/2022/11/07/scala-3.2.1-released.html"
  id.withExtraAttributes(id.extraAttributes + releaseNotesUrl)
}

(Thanks to @julienrf for this snippet!)

Mill:

// in object foo extends PublishModule
  def publishProperties = super.publishProperties() ++ Map(
    "info.releaseNotesUrl" -> "https://www.scala-lang.org/blog/2022/11/07/scala-3.2.1-released.html"
  )

(Thanks to @lefou for this snippet!)

I hope that you consider making use of the info.releaseNotesUrl property!

7 Likes
2

I opened an issue to see if we can get this added as a setting to sbt, similar to the existing apiURL setting.

Otherwise, we can add it to sbt-typelevel. I assume that all projects should set this, even if the default GitHub release notes URL actually works fine for them?

2 Likes
3

I would say yes. It helps popularizing the property and makes it more likely that other projects and tools pick it up. For Scala Steward it won’t make a difference, because it will only show distinct URLs.

1 Like
4

I was hoping that adding this URL to the pom would solve Scala Steward not adding links to the private GitHub projects, but it doesn’t seem to work. During the run Scala Steward has access to the private repository referenced in project.scm.url, project.url and project.properties.info.releaseNotesUrl of the updated dependency. What is the missing bit?

5

As of sbt 1.9.0 you can now conveniently configure this via the releaseNotesURL setting.

releaseNotesURL := Some(url("https://github.com/sbt/sbt/releases"))
5 Likes