"Fossies" - the Fresh Open Source Software Archive

Member "pmd-src-6.47.0/docs/pages/next_major_development.md" (25 Jun 2022, 82721 Bytes) of package /linux/misc/pmd-src-6.47.0.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "next_major_development.md": 6.46.0_vs_6.47.0.

A hint: This file contains one or more very long lines, so maybe it is better readable using the pure text view mode that shows the contents as wrapped lines within the browser window.


We’re excited to bring you the next major version of PMD! Here is a summary of what is planned for PMD 7.

To give us feedback or to suggest a new feature, drop us a line on Gitter!

Summary

We decided it’s time to have a modernized logo and get rid of the gun. This allows to include the logo in anywhere without offense.

The current tasks are listed here: Integrate new PMD logo #1931

API

The API of PMD has been growing over the years and needs to be cleaned up. The goal is, to have a clear separation between a well-defined API and the implementation, which is internal. This should help us in future development. This however entails some incompatibilities and deprecations, see also the sections New API support guidelines and Planned API removals(#planned-api-removals] below.

Full Antlr Support

PMD 6 only supports JavaCC based grammars, but with Antlr parsers can be generated as well. PMD 7 adds full support for grammars written in Antlr, which allows to leverage existing grammars.

The current tasks are listed here: Support for ANTLR based grammars with Swift as an example language #2499

Documentation

We have quite some ideas how we want to improve the documentation. The goal is, that the documentation is up to date and nearly complete. One big task is, how the built-in rules are presented, so that users can easier see, what exactly is available and decide, which rules are useful for the project at hand.

The current tasks are listed here: Documentations improvements tracker #1139

XPath

PMD 6 supports XPath 1.0 via the Jaxen library. This library is old and unmaintained creating some problems (one of which is duplicated classes in the package org.w3c.dom which is a Java API actually). Therefore XPath 1.0 support will be dropped and we upgrade our XPath 2.0 implementation with Saxon moving on to Saxon HE. This will eventually add support in PMD for XPath 3.1.

The current tasks are listed here: XPath Improvements for PMD 7 #2523

Java

Like the main PMD API, the Java AST has been growing over time and the grammar doesn’t support all edge cases (e.g. annotation are not supported everywhere). The goal is to simplify the AST by reducing unnecessary nodes and abstractions and fix the parsing issues. This helps in the end to provide a better type resolution implementation, but changing the AST is a breaking API change.

Some first results of the Java AST changes are for now documented in the Wiki: Java clean changes.

Miscellaneous

There are also some small improvements, refactoring and internal tasks that are planned for PMD 7.

The current tasks are listed here: PMD 7 Miscellaneous Tasks #2524

New API support guidelines

What’s new

Until now, all released public members and types were implicitly considered part of PMD’s public API, including inheritance-specific members (protected members, abstract methods). We have maintained those APIs with the goal to preserve full binary compatibility between minor releases, only breaking those APIs infrequently, for major releases.

In order to allow PMD to move forward at a faster pace, this implicit contract will be invalidated with PMD 7.0.0. We now introduce more fine-grained distinctions between the type of compatibility support we guarantee for our libraries, and ways to make them explicit to clients of PMD.

.internal packages and @InternalApi annotation

Internal API is meant for use only by the main PMD codebase. Internal types and methods may be modified in any way, or even removed, at any time.

Any API in a package that contains an .internal segment is considered internal. The @InternalApi annotation will be used for APIs that have to live outside of these packages, e.g. methods of a public type that shouldn’t be used outside of PMD (again, these can be removed anytime).

@ReservedSubclassing

Types marked with the @ReservedSubclassing annotation are only meant to be subclassed by classes within PMD. As such, we may add new abstract methods, or remove protected methods, at any time. All published public members remain supported. The annotation is not inherited, which means a reserved interface doesn’t prevent its implementors to be subclassed.

@Experimental

APIs marked with the @Experimental annotation at the class or method level are subject to change. They can be modified in any way, or even removed, at any time. You should not use or rely on them in any production code. They are purely to allow broad testing and feedback.

@Deprecated

APIs marked with the @Deprecated annotation at the class or method level will remain supported until the next major release but it is recommended to stop using them.

The transition

All currently supported APIs will remain so until 7.0.0. All APIs that are to be moved to .internal packages or hidden will be tagged @InternalApi before that major release, and the breaking API changes will be performed in 7.0.0.

Planned API removals

List of currently deprecated APIs

{% include warning.html content=“This list is not exhaustive. The ultimate reference is whether an API is tagged as @Deprecated or not in the latest minor release. During the development of 7.0.0, we may decide to remove some APIs that were not tagged as deprecated, though we’ll try to avoid it.” %}

6.47.0

No changes.

6.46.0

Deprecated ruleset references

Ruleset references with the following formats are now deprecated and will produce a warning when used on the CLI or in a ruleset XML file: - <lang-name>-<ruleset-name>, eg java-basic, which resolves to rulesets/java/basic.xml - the internal release number, eg 600, which resolves to rulesets/releases/600.xml

Use the explicit forms of these references to be compatible with PMD 7.

Deprecated API
Internal API

Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

6.45.0

Experimental APIs

6.44.0

Deprecated API
Experimental APIs

6.43.0

Deprecated API

Some API deprecations were performed in core PMD classes, to improve compatibility with PMD 7. - {% jdoc core::Report %}: the constructor and other construction methods like addViolation or createReport - {% jdoc core::RuleContext %}: all constructors, getters and setters. A new set of stable methods, matching those in PMD 7, was added to replace the addViolation overloads of {% jdoc core::lang.rule.AbstractRule %}. In PMD 7, RuleContext will be the API to report violations, and it can already be used as such in PMD 6. - The field {% jdoc core::PMD#configuration %} is unused and will be removed.

Internal API

Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

Changed API

It is now forbidden to report a violation: - With a null node - With a null message - With a null set of format arguments (prefer a zero-length array)

Note that the message is set from the XML rule declaration, so this is only relevant if you instantiate rules manually.

{% jdoc core::RuleContext %} now requires setting the current rule before calling {% jdoc core::Rule#apply(java.util.List, core::RuleContext) %}. This is done automatically by RuleSet#apply and such. Creating and configuring a RuleContext manually is strongly advised against, as the lifecycle of RuleContext will change drastically in PMD 7.

6.42.0

No changes.

6.41.0

Command Line Interface

The command line options for PMD and CPD now use GNU-syle long options format. E.g. instead of -rulesets the preferred usage is now --rulesets. Alternatively one can still use the short option -R. Some options also have been renamed to a more consistent casing pattern at the same time (--fail-on-violation instead of -failOnViolation). The old single-dash options are still supported but are deprecated and will be removed with PMD 7. This change makes the command line interface more consistent within PMD and also less surprising compared to other cli tools.

The changes in detail for PMD:

old option new option
-rulesets --rulesets (or -R)
-uri --uri
-dir --dir (or -d)
-filelist --file-list
-ignorelist --ignore-list
-format --format (or -f)
-debug --debug
-verbose --verbose
-help --help
-encoding --encoding
-threads --threads
-benchmark --benchmark
-stress --stress
-shortnames --short-names
-showsuppressed --show-suppressed
-suppressmarker --suppress-marker
-minimumpriority --minimum-priority
-property --property
-reportfile --report-file
-force-language --force-language
-auxclasspath --aux-classpath
-failOnViolation --fail-on-violation
--failOnViolation --fail-on-violation
-norulesetcompatibility --no-ruleset-compatibility
-cache --cache
-no-cache --no-cache

The changes in detail for CPD:

old option new option
--failOnViolation --fail-on-violation
-failOnViolation --fail-on-violation
--filelist --file-list

6.40.0

Experimental APIs

6.39.0

No changes.

6.38.0

No changes.

6.37.0

PMD CLI
Experimental APIs
Internal API

Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

6.36.0

No changes.

6.35.0

Deprecated API

6.34.0

No changes.

6.33.0

No changes.

6.32.0

Experimental APIs
Internal API

Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

6.31.0

Deprecated API
Experimental APIs

6.30.0

Deprecated API
Around RuleSet parsing
Around the PMD class

Many classes around PMD’s entry point ({% jdoc core::PMD %}) have been deprecated as internal, including: * The contents of the packages {% jdoc_package core::cli %}, {% jdoc_package core::processor %} * {% jdoc core::SourceCodeProcessor %} * The constructors of {% jdoc core::PMD %} (the class will be made a utility class)

Miscellaneous
Internal API

Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

6.29.0

No changes.

6.28.0

Deprecated API
For removal

6.27.0

Deprecated API
For removal

6.26.0

Deprecated API
For removal

6.25.0

Deprecated APIs
Internal API

Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

For removal

6.24.0

Deprecated APIs
Experimental APIs

Note: Experimental APIs are identified with the annotation {% jdoc core::annotation.Experimental %}, see its javadoc for details

6.23.0

Deprecated APIs
Internal API

Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

In ASTs

As part of the changes we’d like to do to AST classes for 7.0.0, we would like to hide some methods and constructors that rule writers should not have access to. The following usages are now deprecated in the Apex, Javascript, PL/SQL, Scala and Visualforce ASTs:

These deprecations are added to the following language modules in this release. Please look at the package documentation to find out the full list of deprecations. * Apex: {% jdoc_package apex::lang.apex.ast %} * Javascript: {% jdoc_package javascript::lang.ecmascript.ast %} * PL/SQL: {% jdoc_package plsql::lang.plsql.ast %} * Scala: {% jdoc_package scala::lang.scala.ast %} * Visualforce: {% jdoc_package visualforce::lang.vf.ast %}

These deprecations have already been rolled out in a previous version for the following languages: * Java: {% jdoc_package java::lang.java.ast %} * Java Server Pages: {% jdoc_package jsp::lang.jsp.ast %} * Velocity Template Language: {% jdoc_package vm::lang.vm.ast %}

Outside of these packages, these changes also concern the following TokenManager implementations, and their corresponding Parser if it exists (in the same package):

In the Java AST the following attributes are deprecated and will issue a warning when used in XPath rules:

For removal

6.22.0

Deprecated APIs
Internal API

Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

For removal
In ASTs (JSP)

As part of the changes we’d like to do to AST classes for 7.0.0, we would like to hide some methods and constructors that rule writers should not have access to. The following usages are now deprecated in the JSP AST (with other languages to come):

Please look at {% jdoc_package jsp::lang.jsp.ast %} to find out the full list of deprecations.

In ASTs (Velocity)

As part of the changes we’d like to do to AST classes for 7.0.0, we would like to hide some methods and constructors that rule writers should not have access to. The following usages are now deprecated in the VM AST (with other languages to come):

Please look at {% jdoc_package vm::lang.vm.ast %} to find out the full list of deprecations.

PLSQL AST

The production and node ASTCursorBody was unnecessary, not used and has been removed. Cursors have been already parsed as ASTCursorSpecification.

6.21.0

Deprecated APIs
Internal API

Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

For removal

6.20.0

No changes.

6.19.0

Deprecated APIs
For removal
Internal APIs

6.18.0

Changes to Renderer
Deprecated APIs
For removal
Internal APIs

Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0. You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

6.17.0

No changes.

6.16.0

Deprecated APIs

Reminder: Please don’t use members marked with the annotation {% jdoc core::annotation.InternalApi %}, as they will likely be removed, hidden, or otherwise intentionally broken with 7.0.0.

In ASTs

As part of the changes we’d like to do to AST classes for 7.0.0, we would like to hide some methods and constructors that rule writers should not have access to. The following usages are now deprecated in the Java AST (with other languages to come):

Please look at {% jdoc_package java::lang.java.ast %} to find out the full list of deprecations.

6.15.0

Deprecated APIs
For removal

6.14.0

No changes.

6.13.0

Command Line Interface

The start scripts run.sh, pmd.bat and cpd.bat support the new environment variable PMD_JAVA_OPTS. This can be used to set arbitrary JVM options for running PMD, such as memory settings (e.g. PMD_JAVA_OPTS=-Xmx512m) or enable preview language features (e.g. PMD_JAVA_OPTS=--enable-preview).

The previously available variables such as OPTS or HEAPSIZE are deprecated and will be removed with PMD 7.0.0.

Deprecated API

6.12.0

No changes.

6.11.0

6.10.0

Properties framework

{% jdoc_nspace :props core::properties %} {% jdoc_nspace :PDr props::PropertyDescriptor %} {% jdoc_nspace :PF props::PropertyFactory %}

The properties framework is about to get a lifting, and for that reason, we need to deprecate a lot of APIs to remove them in 7.0.0. The proposed changes to the API are described on the wiki

Changes to how you define properties

Here’s an example:

// Before 7.0.0, these are equivalent:
IntegerProperty myProperty = new IntegerProperty("score", "Top score value", 1, 100, 40, 3.0f);
IntegerProperty myProperty = IntegerProperty.named("score").desc("Top score value").range(1, 100).defaultValue(40).uiOrder(3.0f);

// They both map to the following in 7.0.0
PropertyDescriptor<Integer> myProperty = PropertyFactory.intProperty("score").desc("Top score value").require(inRange(1, 100)).defaultValue(40);

You’re highly encouraged to migrate to using this new API as soon as possible, to ease your migration to 7.0.0.

Architectural simplifications
Changes to the PropertyDescriptor interface
Deprecated APIs

{% jdoc_nspace :xpath core::lang.ast.xpath %} {% jdoc_nspace :jast java::lang.java.ast %} {% jdoc_nspace :rule core::Rule %} {% jdoc_nspace :lvh core::lang.LanguageVersionHandler %} {% jdoc_nspace :rset core::RuleSet %} {% jdoc_nspace :rsets core::RuleSets %}

For internalization
For removal

6.9.0

No changes.

6.8.0

6.7.0

6.5.0

6.4.0

6.2.0

6.1.0

6.0.1

List of currently deprecated rules