We need to:

• Deprecate XPathRuleQuery, which was internal API anyway --> [core] Deprecate Jaxen and XPath internal API  #2407
• Deprecate Node#findChildrenWithXPath, which throws a Jaxen-specific checked exception. It's also superseded by [core] NodeStream API #1622
• Write up a doc page about how to migrate --> [docs] Update docs about writing rules #2267
  • Theoretically relevant incompatibilities:
    • XPath spec
    • [core] Inconsistent boolean value representation with Jaxen #1244
    • [core] Jaxen adapter implements document nodes incorrectly #1938
  • Incompatibilities I've really found while migrating all our built-in rules:
    • Prefixes fn: and string: should not be mentioned explicitly. Saxon complains about an undeclared namespace, but the functions are in the default namespace. Removing the namespace prefixes fixes it. We could declare them explicitly though, which would likely work
    • Boolean comparisons, [core] Inconsistent boolean value representation with Jaxen #1244. A simple search and replace for "false" and "true" (and single quote variants) fixes that one. Since they're keywords in the languages we analyse they can never occur in identifiers or other unexpected places.
    • Adding pmd-java: namespace to calls to our custom functions.
    • Type errors when comparing a number to a string. In 1.0 the string is coerced to a number. Again search and replace works.
    • Some errors are caused by the fact our implementation of saxon wrappers is incomplete or otherwise wrong, but those are bugs on our side. E.g. AttributeNode doesn't implement getParent, and a DocumentNode represents the root node which is wrong: every ast node, even the root, should be mapped to an ElementNode, the document node is a virtual node that exists outside of the DOM for saxon.
    • That's all

So migration cost is very low and a bunch of regex search and replace is probably enough to migrate any rule automatically. That could be done by the ruleset migration tool.

Consequently I don't see a need to issue a warning to users that still use 1.0. Especially so since we're going to make changes to the grammar for 7.0.0, so that telling them now to update to XPath 2.0, then telling them on 7.0.0 that anyway their updated rules most probably don't work anymore and need to be rewritten could be seen as a dick move.

The most inconvenienced users will be clients of the programmatic API of XPathRule, but that's not the only API which will be broken by 7.0.0 anyway. Deprecated annotations should be enough to warn them in advance.

Upgrading to Saxon HE also would provide much value, including support for XPath 3.1, and a super clean API to implement custom functions, and a cleaner API to implement external DOM wrappers. It drops support for XPath 1.0 compatibility mode, which is not a big loss, as the incompatibilities it prevented are corner cases and are realistically very rare in XPath rules.