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

Show release notes URL from POM in PR body #2863

Merged
merged 16 commits into from
Jan 3, 2023

Conversation

fthomas
Copy link
Member

@fthomas fthomas commented Dec 28, 2022

This PR shows a release notes URL from the POM in the body of PRs.

Currently, Scala Steward uses the project.scm.url or project.url and tries to find release notes / change logs / version diffs from these URLs by constructing common URLs and checking if they exist. These are then added to the PRs.

With this change, Scala Steward also reads a release notes URL from a project.properties."info.releaseNotesUrl" element in the POM and shows it in the PR body. It allows library maintainers to have their release notes anywhere they want them to be and still have Scala Steward show them in PRs. Note that I just made up the name releaseNotesUrl for this feature.

This has been partly motivated by com-lihaoyi/requests-scala#122. The changes in CoursierAlg also allow to extract more metadata in the future to maybe implement the idea @lefou mentioned in #2708 (comment).

/ping @ckipp01 and @lefou since I mentioned this the other day on Discord.

Open questions:

  • Is there prior art of adding release notes or changelog URLs to the POM? Maybe we can reuse some convention of adding URLs to the POM that other projects already use.
  • If not, is it okay to use releaseNotesUrl or should the element name be prefixed with scalasteward. or something like that?

@codecov
Copy link

codecov bot commented Dec 28, 2022

Codecov Report

Base: 86.97% // Head: 88.23% // Increases project coverage by +1.26% 🎉

Coverage data is based on head (b9b525a) compared to base (7e1c995).
Patch coverage: 94.11% of modified lines in pull request are covered.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #2863      +/-   ##
==========================================
+ Coverage   86.97%   88.23%   +1.26%     
==========================================
  Files         156      157       +1     
  Lines        2994     3018      +24     
  Branches      201      203       +2     
==========================================
+ Hits         2604     2663      +59     
+ Misses        390      355      -35     
Impacted Files Coverage Δ
...la/org/scalasteward/core/application/Context.scala 68.42% <ø> (ø)
...ala/org/scalasteward/core/nurture/NurtureAlg.scala 18.66% <87.50%> (+18.66%) ⬆️
...a/org/scalasteward/core/coursier/CoursierAlg.scala 96.07% <94.28%> (+24.33%) ⬆️
...calasteward/core/coursier/DependencyMetadata.scala 100.00% <100.00%> (ø)
...rc/main/scala/org/scalasteward/core/util/uri.scala 100.00% <100.00%> (ø)
.../scala/org/scalasteward/core/vcs/VCSExtraAlg.scala 100.00% <100.00%> (ø)
.../scala/org/scalasteward/core/data/UpdateData.scala 100.00% <0.00%> (+50.00%) ⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

@ckipp01
Copy link
Contributor

ckipp01 commented Dec 29, 2022

Is there prior art of adding release notes or changelog URLs to the POM? Maybe we can reuse some convention of adding URLs to the POM that other projects already use.

I dug around a bit to see if I could find anything and the only thing I found is that some release plugins will use this same convention. For example you can see this in a couple apache Maven projects that use properties.commons.releaseNotesLocation. Here are a couple examples:

If not, is it okay to use releaseNotesUrl or should the element name be prefixed with scalasteward. or something like that?

I like releaseNotesUrl. It's clear. I actually don't think we should prefix it with scalasteward. This might be a good opportunity to introduce something that various tools in theory could use. So I'm in favor of leaving in generic.

Thanks for diving into this @fthomas!

@fthomas
Copy link
Member Author

fthomas commented Dec 29, 2022

I like releaseNotesUrl. It's clear. I actually don't think we should prefix it with scalasteward. This might be a good opportunity to introduce something that various tools in theory could use. So I'm in favor of leaving in generic.

I agree with that and also think that it could be less likely that people adopt that property if it is tied to Scala Steward. At least I wouldn't want to sprinkle my POMs with tool specific properties.

@fthomas
Copy link
Member Author

fthomas commented Dec 29, 2022

Btw, I'd like to note that the idea of adding a release notes URL to the POM has been discussed before in the
"Coordinate compiler and tooling releases?"
thread on the Scala Contributors forum although it was discussed for the purpose of delaying PRs until a library is announced.

@fthomas
Copy link
Member Author

fthomas commented Dec 31, 2022

Just noticed that with this change #2541 proposed by @julienrf should be almost trivial to implement by adding a new versionScheme field to DependencyMetadata and using that in NewPullRequestData.

@fthomas
Copy link
Member Author

fthomas commented Jan 2, 2023

I just looked at the POM of Cats 2.9.0. It contains these properties:

<properties>
  <info.apiURL>https://www.javadoc.io/doc/org.typelevel/cats-docs_2.13/2.9.0/</info.apiURL>
  <info.versionScheme>early-semver</info.versionScheme>
</properties>

Both come from the corresponding sbt settings apiURL and versionScheme. I don't know if there is something special about the info prefix but sbt is using that for the settings it writes into the POM. I'm now tempted to imitate sbt here and to require the info prefix for releaseNotesUrl too.

@fthomas
Copy link
Member Author

fthomas commented Jan 2, 2023

The last commit changed the key to info.releaseNotesUrl. Matching the key is done case-insensitive, so it will also match info.releaseNotesURL or any other capitalisation. The added NurtureAlgTest demonstrates that URLs are still displayed correctly for a simple update. As far as I'm concerned this is ready to be merged.

@fthomas fthomas added the enhancement New feature or request label Jan 2, 2023
@fthomas fthomas added this to the 0.20.0 milestone Jan 2, 2023
@ckipp01
Copy link
Contributor

ckipp01 commented Jan 3, 2023

The last commit changed the key to info.releaseNotesUrl. Matching the key is done case-insensitive, so it will also match info.releaseNotesURL or any other capitalisation. The added NurtureAlgTest demonstrates that URLs are still displayed correctly for a simple update. As far as I'm concerned this is ready to be merged.

Awesome. I don't want to steal your thunder so I didn't do it, but you might want to announce this new feature in https://contributors.scala-lang.org/ so that more people are aware of it. Basically all over the place, ha.

Copy link
Member

@alejandrohdezma alejandrohdezma left a comment

Choose a reason for hiding this comment

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

👏🏼 👏🏼

Copy link
Member

@mzuehlke mzuehlke left a comment

Choose a reason for hiding this comment

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

Would you update the reference to the new property in the PR description, there you are still referring to project.properties.releaseNotesUrl

Duplicates could have happened if the URL from the POM was the same as
one of the URLs constructed in possibleReleaseRelatedUrls.
@fthomas fthomas merged commit 2157fae into main Jan 3, 2023
@fthomas fthomas deleted the topic/grab-release-notes-url-from-pom branch January 3, 2023 15:00
@fthomas
Copy link
Member Author

fthomas commented Jan 4, 2023

Update: See #2863 (comment) for a better way to add this property in sbt.

Btw, in sbt the info.releaseNotesUrl property can be added to the POM vie pomPostProcess:

pomPostProcess := { (node: xml.Node) =>
  val releaseNotesUrl =
    <info.releaseNotesUrl>https://www.scala-lang.org/blog/2022/11/07/scala-3.2.1-released.html</info.releaseNotesUrl>
  var updated = false
  val updatedChild = node.child.map {
    case e: xml.Elem if e.label == "properties" =>
      updated = true; e.copy(child = e.child :+ releaseNotesUrl)
    case n => n
  }
  node match {
    case e: xml.Elem if updated => e.copy(child = updatedChild)
    case e: xml.Elem => e.copy(child = e.child :+ <properties>{releaseNotesUrl}</properties>)
    case n           => n
  }
}

This adds the info.releaseNotesUrl to an existing properties element or adds the properties element with a sole info.releaseNotesUrl element if the former does not exist.

Not sure if there is an easier way to do it. It would be certainly nice if this wouldn't be so complicated.

@lefou
Copy link
Member

lefou commented Jan 4, 2023

In Mill, you can add the property as follows:

// 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"
  )

@julienrf
Copy link
Contributor

julienrf commented Jan 4, 2023

@fthomas I think there is a simpler way for 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)
}

@fthomas
Copy link
Member Author

fthomas commented Jan 4, 2023

Awesome, thanks @julienrf!

fthomas added a commit that referenced this pull request Jan 6, 2023
This is a follow-up to #2863. Before this change, the `info.releaseNotesUrl`
property from the POM was ignored if `project.scm.url` and `project.url`
were not set. With this change the `releaseNotesUrl` is added to the PR
even if the other two are not set.
@fthomas
Copy link
Member Author

fthomas commented Jan 7, 2023

Just announced this on Scala Contributors: https://contributors.scala-lang.org/t/add-release-notes-urls-to-your-poms/6059

Update: Here is a GitHub search of issues that mention info.releaseNotesUrl: https://github.com/search?q=info.releaseNotesUrl&type=issues

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

6 participants