Listing upgrades in the release notes

Development
#1

Hello all,

I’d like to propose a small automation of the way we list upgrades in release notes.

How we do currently

In a release note (e.g., 16.3.0-rc-1 release note), the Upgrades section is maintained manually and is a list of ${dependencyName} ${dependencyVersion} items, wrapping in links to the correspinding jira issues.

For instance:

The sources being:

* [[dompurify 3.1.0>>https://jira.xwiki.org/browse/XWIKI-22014]]
* [[guava 33.1.0-jre>>https://jira.xwiki.org/browse/XCOMMONS-2973]]
* [[plexus archiver 4.9.2>>https://jira.xwiki.org/browse/XCOMMONS-2971]]

And each listed issue has a Documentation in Release Notes: filled with a link to the HUpgrades anchor of the release note

Proposal

Option 1: using the Jira macro

Replace the manually maintained list of issues with a jira macro.

Example for the 16.3.0 release:

{{jira url="https://jira.xwiki.org" source="jql" style="list"}}
project in (XWIKI, XCOMMONS, XRENDERING) AND issuetype = Task AND fixVersion in (16.3.0, 16.3.0-rc-1) AND component = "Dependency Upgrades"
{{/jira}}

Giving the following result:
image

  • The issues id are explicitly mentioned
  • The sentences are changed to Upgrade to ${dependencyName} ${dependencyVersion}
  • The links are crossed since the issues are closed (note: if this is the only blocking point, it is easy to define a custom css style to remove the default text-decoration-line: line-through; for the del elements wrapping the links content)

Option 2: Using the jira scripting extension

Reading https://extensions.xwiki.org/xwiki/bin/view/Extension/JIRA%20Module, it seems possible to have an even finer control of the rendering with something like the code below (thanks @vmassol for the suggestion).
But, my first attempts are not successful and the call to getJiraRestClient returns an empty value.

{{velocity}}
#set ($client = $services.jira.getJiraRestClient('clientId'))
#set ($pm = $services.jira.getNullProgressMonitor())
#foreach ($basicIssue in $client.getSearchClient().searchJql('jira search query', $pm).getIssues())
  * [[${description}>>${issue link}]]
#end
{{/velocity}}

Conclusion

Do you thinks automating this listing is interesting?
Then, do you think option 1 is good enough or should I keep investigating option 2?

Thanks

Note: this proposal is only about generating the list automatically, the rest of the process is not changed. For instance, we’d keep maintaining the Documentation in Release Notes: field in the issues.

#2

Yes, I like it.

One small drawback is that we’ll have some “dups” (with different versions) when a depo is upgraded in RC and final.

I prefer option 2 and I need to debug it since I also couldn’t make it work yesterday and this is bothering me.

I think we should change that and allow N/A to be used for dep upgrades. Otherwise the benefits are less.

Thanks

#3

The first reason was that you need to install the JIRA Scripting API extension :slight_smile: But it’s still not working, probably because it’s using an old version not compatible with our jira version. I’m trying to upgrade.

1 Like
#4

Yes, it’s good enough.

I’m not sure it makes sense to keep that. The real goal of this field is to not forget about adding an entry in the release note, and if the list is automated then it’s impossible to forget it.

Not really, we already have this problem.

To me, the only drawback is that it makes the list a little more fragile, but we are already using the jira macro for other things (including listing dependencies upgrades, in the rare case of a bugfix versions).

#5

Not really, right now we manually merge the updates from RC and final and we can manually remove the unnecessary entry. With the automated solution, we cannot (but it’s not a blocker for me).

A small problem is that the text is dependent on the author of the issue. Some use the pattern “Upgrade to XXX”. Others use “Upgrade XXX to”.

However, this small inconsistency is probably acceptable.

#6

I’m not sure what you mean by merging. If you just remove “duplicates” from the list in the RN (which I definitely don’t do) then it’s a mistake since the target jira issue does not contain the whole change.

#7

Take the updates from the RC RN and copy them to the final RN.

See You're invited to talk on Matrix and You're invited to talk on Matrix

The final RN is not correct for Commons Configuration since it should only mention v2.10.1 and not 2.10.0.

#8

Again, it’s not that simple: that list also links to where you can find what changed and if you have only one jira issue you see only part of what changed.

#9

After installing org.xwiki.contrib.jira:jira-api, I got the error at Loading..., which I’ve solved with Loading... but which is blocked by Loading... :slight_smile: