Merge remote-tracking branch 'origin/master' into pmd/7.0.x

docs/pages/release_notes.md

@@ -19,6 +19,51 @@ This is a {{ site.pmd.release_type }} release.
 
 ### New and noteworthy
 
+#### Better XML XPath support
+
+The new rule class {% jdoc xml::lang.xml.rule.DomXPathRule %} is intended to replace
+usage of the `XPathRule` for XML rules. This rule executes the XPath query in a different
+way, which sticks to the XPath specification. This means the expression is interpreted
+the same way in PMD as in all other XPath development tools that stick to the standard.
+You can for instance test the expression in an online XPath editor.
+
+Prefer using this class to define XPath rules: replace the value of the `class`
+attribute with `net.sourceforge.pmd.lang.xml.rule.DomXPathRule` like so:
+```xml
+<rule name="MyXPathRule"
+      language="xml"
+      message="A message"
+      class="net.sourceforge.pmd.lang.xml.rule.DomXPathRule">
+
+      <properties>
+        <property name="xpath">
+            <value><![CDATA[
+            /a/b/c[@attr = "5"]
+            ]]></value>
+        </property>
+        <!-- Note: the property "version" is ignored, remove it. The query is XPath 2. -->
+      </properties>
+</rule>
+```
+
+The rule is more powerful than `XPathRule`, as it can now handle XML namespaces,
+comments and processing instructions. Please refer to the Javadoc of {% jdoc xml::lang.xml.rule.DomXPathRule %}
+for information about the differences with `XPathRule` and examples.
+
+`XPathRule` is still perfectly supported for all other languages, including Apex and Java.
+
+#### New XPath functions
+
+The new XPath functions `pmd:startLine`, `pmd:endLine`, `pmd:startColumn`,
+and `pmd:endColumn` are now available in XPath rules for all languages. They
+replace the node attributes `@BeginLine`, `@EndLine` and such. These attributes
+will be deprecated in a future release.
+
+Please refer to [the documentation](https://pmd.github.io/latest/pmd_userdocs_extending_writing_xpath_rules.html#pmd-extension-functions) of these functions for more information, including usage samples.
+
+Note that the function `pmd:endColumn` returns an exclusive index, while the
+attribute `@EndColumn` is inclusive. This is for forward compatibility with PMD 7,
+which uses exclusive end indices.
 
 #### New programmatic API
 
@@ -65,6 +110,9 @@ The CLI itself remains compatible, if you run PMD via command-line, no action is
 *   doc
     *   [#2504](https://github.com/pmd/pmd/issues/2504): \[doc] Improve "Edit me on github" button
     *   [#3812](https://github.com/pmd/pmd/issues/3812): \[doc] Documentation website table of contents broken on pages with many subheadings
+*   xml
+    *   [#2766](https://github.com/pmd/pmd/issues/2766): \[xml] XMLNS prefix is not pre-declared in xpath query
+    *   [#3863](https://github.com/pmd/pmd/issues/3863): \[xml] Make XPath rules work exactly as in the XPath spec
 
 ### API Changes
 

pmd-xml/src/main/java/net/sourceforge/pmd/lang/xml/rule/DomXPathRule.java

@@ -125,6 +125,8 @@ public class DomXPathRule extends AbstractRule {
     public DomXPathRule() {
         definePropertyDescriptor(XPATH_EXPR);
         definePropertyDescriptor(DEFAULT_NS_URI);
+        // for compatibility, but is ignored.
+        definePropertyDescriptor(XPathRule.VERSION_DESCRIPTOR);
     }