Start providing version in revapi ignores

Development
1

Hi everyone,

so we have this problem for a while (EDIT: it is actually ticket Loading...) that currently the revapi ignores we put in our pom.xml doesn’t contain any version information. It’s a problem because when we’re performing a release we cleanup the revapi ignores, and some might have been added in master after the branch where to perform the release was created and our tools currently cannot guess easily which ignores to remove.

So my proposal is to start using the `attachments` elements of revapi schema: Differences Transformation :: Revapi . This element is basically a map that we use the way we want. I propose that we use an element `version` in it, containing the version the revapi ignore targets.

For example, in master before a 18.8.0 release I could have:

<revapi.differences>
  <justification>The justification for breaking stuff</justification>
  <criticality>highlight</criticality>
  <attachments>
    <version>18.8.0</version>
    <version>18.4.7</version>
  </attachments>
  <differences>
    <item>
      <ignore>true</ignore>
      <code>java.method.removed</code>
      <old>method boolean org.xwiki.user.UserManager::myMethod()</old>
    </item>
  </differences>
</revapi.differences>
<revapi.differences>
  <justification>The justification for breaking stuff</justification>
  <criticality>highlight</criticality>
  <attachments>
    <version>18.9.0-rc-1</version>
    <version>18.4.7</version>
    <version>17.10.14</version>
  </attachments>
  <differences>
    <item>
      <ignore>true</ignore>
      <code>java.method.removed</code>
      <old>method boolean org.xwiki.user.UserManager::someOtherMethod()</old>
    </item>
  </differences>
</revapi.differences>

Then calling the compatibility cleanup on master after releasing 18.8.0 would only remove the first occurence. The algorithm would be to remove all occurences matching the version released basically.

The fact that we can put multiple version is only to help backporting without having to edit the ignores. We could also do it without that support if we want to avoid any mistake, and force people having to put the version manually.

Now I guess we should have a way to verify that any time we put a ignore we also have the version attached, I’m not sure at this point how it’s doable.

WDYT?

2

+1

I guess that should not be too hard to implement that in an enforcer rule. It would also be in charge of making sure one of the version really matches the current branch next version.

3

If I read the schema definition correctly the same key is not accepted several times in the attachments element, so I suggest moving to a comma separated format instead.
Maybe with a best practice to always list version from the most recent to the least.

<attachments>
  <versions>18.9.0-rc-1,18.4.7,17.10.14</versions>
</attachments>

+1 for the tool support that feels essential to make this work.

4

+1 overall, I’m just wondering if we actually need to list all the target versions here. If it’s only a technical information for our scripts, it might be less error prone to add a “update revapi difference version” to the backport process, no?

5

Honestly I’m not sure either about this. In some cases you know in advance in which branch the backport ignores will be exactly the same, in some other you don’t. So the idea behind my proposal would be to allow providing multiple version, but I wouldn’t enforce it: if a dev prefer to indicate a unique version per ignore per branch it’s perfectly fine.