docs: versioning should not be combined with matchUpdateTypes

[colinodell]

Changes

Documents an edge case that may produce unexpected results for users.

Context

We had a user create a packageRule like this:

{
  "matchManagers": ["maven", "gradle"],
  "matchUpdateTypes": ["patch"],
  "versioning": "regex:^(?<major>\\d+)(\\.(?<minor>\\d+))?(\\.(?<patch>\\d+))?([-\\.](?<compatibility>.*))?$",
  "groupName": "jvm-patch-with-compatibility"
}

With this rule in place, Renovate opened a PR tying to upgrade a Maven dependency from 9.4.1.jre8 to 9.4.1.jre16 as a patch update, which was unexpected to them.

After debugging, we confirmed that the custom versioning never took effect because of a chicken-and-egg problem. Basically, Renovate tries to apply package rules several times at different points in time, like:

1. Before fetching all available packages, to figure out which versioning scheme to use throughout the rest of the dependency update process
2. While considering what to do (if anything) for each available dependency release

That first time, it skipped the user's rule because it said it only applied to patch-level updates, but Renovate didn’t yet have that information to match against. That meant the versioning was never applied in "step 1", so it fell back to its default Maven handling. Then, when it had all the available versions in "step 2", it saw that Maven considered those to be patch releases, so the rule kicked in at that point, but it was too late for the versioning to do anything (so it only applied the grouping stuff).

It would therefore be helpful to document that rules defining the versioning should not also define matchUpdateTypes to avoid this behavior. (Splitting the rule into two - one for versioning and another for grouping - fixed this for the user.)

Alternatively, it might be useful to raise some kind of proactive warning if a user configures both versioning and matchUpdateTypes in the same rule, but I figured documenting this limitation wouldn't hurt.

Documentation (please check one with an [x])

• I have updated the documentation, or
• No documentation update is required

How I've tested my work (please tick one)

I have verified these changes via:

• Code inspection only, or
• Newly added/modified unit tests, or
• No unit tests but ran on a real repository, or
• Both unit tests + ran on a real repository

[renovate-release]

🎉 This PR is included in version 32.162.0 🎉

The release is available on:

• GitHub release
• 32.162.0

Your semantic-release bot 📦🚀