Skip to content

Updating the website to the (upoming) jackpot30 20.0 #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jlahoda wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Updating the website to the (upoming) jackpot30 20.0 #11

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 36 additions & 7 deletions modules/ROOT/pages/jackpot/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,19 +42,48 @@ For maven projects, this typically means placing the file into `src/main/resourc

The format of the file is described xref:./HintsFileFormat.adoc[here].

== Using Maven to Run Declarative Refactorings
== Using Maven to Run Declarative Refactorings or Standard Java Hints

To use run the declarative hints in a Maven project, add the tool to the build plugins in pom.xml:
[source,java]
To use the declarative hints or standard Java hints in a Maven project, either for verification,
or for transformation, add the tool to the build plugins in pom.xml:
[source,xml]
----
<plugin>
<groupId>org.apache.netbeans.modules.jackpot30</groupId>
<artifactId>jackpot30-maven-plugin</artifactId>
<version>13.0</version>
<version>20.0</version>
</plugin>
----

And declare the hints in `.hint` files under `src/main/resources/META-INF/upgrade`, for example:
Configuration can be specified like this:
[source,xml]
----
<plugin>
<groupId>org.apache.netbeans.modules.jackpot30</groupId>
<artifactId>jackpot30-maven-plugin</artifactId>
<version>20.0</version>
<configuration>
<hint>SizeReplaceableByIsEmpty</hint>
Copy link
Copy Markdown

@jtulach jtulach Jan 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having a list of available values somewhere would be benefitial.

Having such list in a documentation would help people understand the value of Jackpot without trying it out manually.

<failOnWarnings>true</failOnWarnings>
</configuration>
</plugin>
----

Supported configuration options are:

- `hint`: the hint or hints that should be invoked. Can either be a comma-separated list of `@SuppressWarnings` keys of hints to invoke, or the display name of the hint to invoke,
- `configuration`: a configuration file (from NetBeans) specifying which hints should be run,
Copy link
Copy Markdown

@jtulach jtulach Jan 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Description how to obtain such configuration file is needed, otherwise it is not clear at all how to get it.

- `failOnWarnings`: when `true`, and any warning will be printed, the build will fail.

Supported goals are:

- `jackpot30:analyze`: run the hints, and print warnings produce by them possible failing the build, as specified,
Copy link
Copy Markdown

@jtulach jtulach Jan 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `jackpot30:analyze`: run the hints, and print warnings produce by them possible failing the build, as specified,
- `jackpot30:analyze`: run the hints, and print warnings produce by them possibly failing the build, as specified,

- `jackpot30:apply`: run the hints, and apply the primary proposed changes on each place where the hint would produce a warning. Please note this will be applied directly into the working copy of the files,
- `jackpot30:list`: list the support standard and custom Java hints.
Copy link
Copy Markdown

@jtulach jtulach Jan 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you give example how to check for @NotNull and co. annotations in a project?


=== Using Custom Declarative Hints

It is possible to declare custom hints in `.hint` files under `src/main/resources/META-INF/upgrade`, for example:

.src/main/resources/META-INF/upgrade/convert.hint
[source,java]
Expand All @@ -65,15 +94,15 @@ System.out.println($args$)
;;
----

To get warnings for the declarative hints, run `jackpot30:analyze`:
When there is no more specific configuration (like using `hint`), these will be used when `jackpot30:analyze` is run:
----
$ mvn -q jackpot30:analyze
.../src/main/java/sample/sample/Test.java:14: warning: [convert] convert
System.err.println("args=" + args);
^
----

To apply the changes produced by the declarative hints, run `jackpot30:apply`:
Changes will also be applied on `jackpot30:apply`:
----
$ mvn -q jackpot30:apply && git diff
diff --git a/src/main/java/sample/sample/Test.java b/src/main/java/sample/sample/Test.java
Expand Down