Listing upgrades in the release notes

[mleduc]

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:

• dompurify 3.1.0
• guava 33.1.0-jre
• plexus archiver 4.9.2

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:

• 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.

[vmassol]

@mleduc

Do you thinks automating this listing is interesting?

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.

@mleduc

Then, do you think option 1 is good enough or should I keep investigating option 2?

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

@mleduc

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.

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

Thanks

[vmassol]

@vmassol

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

The first reason was that you need to install the JIRA Scripting API extension 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.

[tmortagne]

@mleduc

Then, do you think option 1 is good enough

Yes, it’s good enough.

@mleduc

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.

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.

@vmassol

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

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).

[vmassol]

@tmortagne

Not really, we already have this problem.

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).

@mleduc

The sentences are changed to Upgrade to ${dependencyName} ${dependencyVersion}

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.

[tmortagne]

@vmassol

Not really, right now we manually merge the updates from RC and final and we can manually remove the unnecessary entry.

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.

[vmassol]

@tmortagne

I’m not sure what you mean by merging.

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

@tmortagne

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.

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.

[tmortagne]

@vmassol

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

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.

[vmassol]

@vmassol

The first reason was that you need to install the JIRA Scripting API extension 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.

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...

[surli]

Hi,

+1 for option 1. And I agree with Thomas: I’m not sure we need to keep the RN doc links in Jira issues then.

[mflorea]

@surli

+1 for option 1. And I agree with Thomas: I’m not sure we need to keep the RN doc links in Jira issues then.

Same on my side.

Thanks,
Marius

[vmassol]

Note that we may want to also list dep upgrades for the XWiki Standalone distribution (or not?). It could be something like what’s on https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.7.0/#HUpgrades

Now I’m wondering if we want to indicate this at all since, if we do it, we may also want to indicate the updates done in the other distributions?

WDYT?

Thanks

[tmortagne]

@vmassol

Note that we may want to also list dep upgrades for the XWiki Standalone distribution (or not?).

I think we want to, but I would just put it in the same list as the others, simply a dependency of a package we distribute.

@vmassol

we may also want to indicate the updates done in the other distributions?

It would make sense.

[surli]

@tmortagne

@vmassol

we may also want to indicate the updates done in the other distributions?

It would make sense.

including docker ?

[tmortagne]

@surli

including docker ?

Sure, that’s something we distribute and the changes in the docker image could have important consequences (like changing the Java version or Tomcat, etc.).

For example, we already indicate upgrades of postgres, mysql and mariadb connectors, and those are not XWiki Standard WAR/Flavor dependencies, they are only distributed with the Docker image and the Debian package.