This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-checkstyle-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new e9bbdd9 Refresh the plugin site and README
e9bbdd9 is described below
commit e9bbdd95b4ac1298b6b34bff57146b58743d5723
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 17 23:13:13 2026 +0000
Refresh the plugin site and README
---
README.md | 119 +++++++---------
.../markdown/examples/custom-checker-config.md.vm | 16 ++-
.../examples/custom-developed-checkstyle.md.vm | 155 +++++++++++----------
.../examples/custom-property-expansion.md.vm | 8 +-
.../markdown/examples/inline-checker-config.md.vm | 107 +++++---------
.../markdown/examples/multi-module-config.md.vm | 14 +-
.../markdown/examples/suppressions-filter.md.vm | 13 +-
.../markdown/examples/upgrading-checkstyle.md.vm | 20 ++-
src/site/markdown/faq.md | 33 +++--
src/site/markdown/history.md.vm | 46 +++---
src/site/markdown/index.md.vm | 85 ++++++-----
src/site/markdown/usage.md.vm | 141 +++++++++++--------
src/site/site.xml | 2 +-
13 files changed, 387 insertions(+), 372 deletions(-)
diff --git a/README.md b/README.md
index c9d2872..cac7a95 100644
--- a/README.md
+++ b/README.md
@@ -14,71 +14,54 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-Contributing to [Apache Maven Checkstyle
Plugin](https://maven.apache.org/plugins/maven-checkstyle-plugin/)
-======================
-
-[][license]
-[](https://search.maven.org/artifact/org.apache.maven.plugins/maven-checkstyle-plugin)
-[](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/plugins/maven-checkstyle-plugin/README.md)
-[][build]
-[][test-results]
-
-
-You have found a bug, or you have an idea for a cool new feature? Contributing
-code is a great way to give something back to the open source community. Before
-you dig right into the code, there are a few guidelines that we need
-contributors to follow so that we can have a chance of keeping on top of
-things.
-
-Getting Started
----------------
-
-+ Make sure you have a [GitHub account](https://github.com/signup/free).
-+ If you're planning to implement a new feature, it makes sense to discuss
your changes
- on the [dev list][ml-list] first.
- This way you can make sure you're not wasting your time on something that
isn't
- considered to be in Apache Maven's scope.
-+ Submit a ticket for your issue, assuming one does not already exist.
- + Clearly describe the issue, including steps to reproduce when it is a bug.
- + Make sure you fill in the earliest version that you know has the issue.
-+ Fork the repository on GitHub.
-
-Making and Submitting Changes
---------------
-
-We accept Pull Requests via GitHub. The [developer mailing list][ml-list] is
the
-main channel of communication for contributors.
-There are some guidelines which will make applying PRs easier for us:
-+ Create a topic branch from where you want to base your work (this is usually
the master branch).
- Push your changes to a topic branch in your fork of the repository.
-+ Make commits of logical units.
-+ Respect the original code style: by using the same [codestyle][code-style],
- patches should only highlight the actual difference, not being disturbed by
any formatting issues:
- + Only use spaces for indentation.
- + Create minimal diffs - disable on save actions like reformat source code
or organize imports.
- If you feel the source code should be reformatted, create a separate PR
for this change.
- + Check for unnecessary whitespace with `git diff --check` before committing.
-+ Make sure you have added the necessary tests (JUnit/IT) for your changes.
-+ Run all the tests with `mvn -Prun-its verify` to assure nothing else was
accidentally broken.
-+ Submit a pull request to the repository in the Apache organization.
-
-If you plan to contribute on a regular basis, please consider filing a
[contributor license agreement][cla].
-
-Additional Resources
---------------------
-
-+ [Contributing
patches](https://maven.apache.org/guides/development/guide-maven-development.html#Creating_and_submitting_a_patch)
-+ [Contributor License Agreement][cla]
-+ [General GitHub documentation](https://help.github.com/)
-+ [GitHub pull request
documentation](https://help.github.com/send-pull-requests/)
-+ [Apache Maven X Account](https://x.com/ASFMavenProject)
-+ [Apache Maven Bluesky Account](https://bsky.app/profile/maven.apache.org)
-+ [Apache Maven Mastodon
Account](https://mastodon.social/deck/@[email protected])
-
-[license]: https://www.apache.org/licenses/LICENSE-2.0
-[ml-list]: https://maven.apache.org/mailing-lists.html
-[code-style]: https://maven.apache.org/developers/conventions/code.html
-[cla]: https://www.apache.org/licenses/#clas
-[maven-wiki]: https://cwiki.apache.org/confluence/display/MAVEN/Index
-[test-results]:
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-checkstyle-plugin/job/master/lastCompletedBuild/testReport/
-[build]:
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-checkstyle-plugin/job/master/
+
+# Apache Maven Checkstyle Plugin
+
+[](https://www.apache.org/licenses/LICENSE-2.0)
+[](https://central.sonatype.com/artifact/org.apache.maven.plugins/maven-checkstyle-plugin)
+[](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/plugins/maven-checkstyle-plugin/README.md)
+[](https://github.com/apache/maven-checkstyle-plugin/actions/workflows/maven-verify.yml)
+
+Runs [Checkstyle](https://checkstyle.org/) on a Maven project. The `check` goal
+logs violations and fails the build; the `checkstyle` and
`checkstyle-aggregate`
+goals write an HTML report, on their own or as part of the project site.
+
+```shell
+mvn checkstyle:check
+mvn checkstyle:checkstyle
+```
+
+The plugin requires Maven 3.9.0 and Java 8, and runs Checkstyle 9.3 by default.
+Projects can [use a newer
Checkstyle](https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/upgrading-checkstyle.html)
+by adding it as a plugin dependency.
+
+- Documentation: <https://maven.apache.org/plugins/maven-checkstyle-plugin/>
+- Issues: <https://github.com/apache/maven-checkstyle-plugin/issues>
+- Security reports: see [SECURITY.md](SECURITY.md); never a public issue
+- Agents and automated tools: see [AGENTS.md](AGENTS.md)
+
+## Build
+
+```shell
+mvn verify
+```
+
+Run the integration tests in `src/it` with the `run-its` profile:
+
+```shell
+mvn -Prun-its verify
+```
+
+Build the plugin site, including the goal pages, with:
+
+```shell
+mvn install -DskipTests
+mvn site -Preporting
+```
+
+## Contributing
+
+Open a pull request against `master`. Discuss larger changes on the
+[developer mailing list](https://maven.apache.org/mailing-lists.html) first.
See the
+[guide to helping with
Maven](https://maven.apache.org/guides/development/guide-helping.html)
+for the general process.
diff --git a/src/site/markdown/examples/custom-checker-config.md.vm
b/src/site/markdown/examples/custom-checker-config.md.vm
index 5e00f38..d1e499b 100644
--- a/src/site/markdown/examples/custom-checker-config.md.vm
+++ b/src/site/markdown/examples/custom-checker-config.md.vm
@@ -23,6 +23,8 @@ specific language governing permissions and limitations
under the License.
-->
+<a id="Using_a_Custom_Checkstyle_Checker_Configuration"></a>
+
# Custom Checkstyle Checker Configuration
You can define a custom [Checker configuration xml
file](https://checkstyle.org/config.html#Checker).
@@ -49,11 +51,13 @@ Use the `configLocation` parameter to reference a custom
Checkstyle Checker conf
</project>
```
-This example makes the plugin check for a file named `checkstyle.xml`.
-It can find the file in the compile scope of the dependencies or in the build
extensions classpath.
+With this example, the plugin looks for `checkstyle.xml` in these places:
+
+- as a file, relative to the project directory or to the directory of a parent
project;
+- as a URL;
+- as a resource on the plugin classpath, for example in a JAR that you add as
a plugin dependency, as the [multimodule example](./multi-module-config.html)
shows.
-The Checkstyle Plugin ships with two predefined configuration definitions.
-It selects the Sun Microsystems definition by default.
+Two predefined configurations ship with Checkstyle, and the plugin uses the
Sun one by default:
-- **sun_checks.xml** - Sun Microsystems Definition (default).
-- **google_checks.xml** - Google Definition.
+- `sun_checks.xml`: [Sun code
conventions](https://checkstyle.org/sun_style.html) (default).
+- `google_checks.xml`: [Google Java
Style](https://checkstyle.org/google_style.html).
diff --git a/src/site/markdown/examples/custom-developed-checkstyle.md.vm
b/src/site/markdown/examples/custom-developed-checkstyle.md.vm
index b5002aa..9744982 100644
--- a/src/site/markdown/examples/custom-developed-checkstyle.md.vm
+++ b/src/site/markdown/examples/custom-developed-checkstyle.md.vm
@@ -23,17 +23,18 @@ specific language governing permissions and limitations
under the License.
-->
+<a id="Using_Custom_Developed_Checkstyle_Checks"></a>
+
# Custom Developed Checkstyle Checks
-This example shows how to create a Maven project for your custom checks.
-The project generates a jar file.
-You then use the jar file in your other projects.
-You add the jar file as a dependency to the Checkstyle Plugin.
+This example shows how to create a Maven project for your own Checkstyle
checks.
+The project builds a JAR file, which you add as a dependency of the Checkstyle
Plugin in your other projects.
+
+A [package names file](https://checkstyle.org/config.html#Packages) named
`checkstyle_packages.xml` in the JAR lets your Checkstyle configuration refer
to the checks by their short names.
-The plugin also lets you define the [package names XML
document](https://checkstyle.org/config.html#Packages).
-This document lets Checkstyle reference your custom check modules.
+This example uses the [example
check](https://checkstyle.org/writing-checks.html#Visitor_in_action) from the
Checkstyle website.
-This example uses the [example
check](https://checkstyle.org/writingchecks.html#Visitor_in_action) from the
Checkstyle website.
+<a id="Structuring_your_project"></a>
Project Structure
-----------------
@@ -45,12 +46,13 @@ mycompany-checkstyle-checks
|-- pom.xml
`-- src
`-- main
- `-- java
- `-- com
- `-- mycompany
- `-- checks
- |-- packagenames.xml
- `-- MethodLimitCheck.java
+ |-- java
+ | `-- com
+ | `-- mycompany
+ | `-- checks
+ | `-- MethodLimitCheck.java
+ `-- resources
+ `-- checkstyle_packages.xml
```
The sections below describe the three files.
@@ -58,6 +60,7 @@ The sections below describe the three files.
#[[### `pom.xml`]]#
This POM adds a dependency on Checkstyle.
+Use the Checkstyle version that the plugin runs; the `provided` scope keeps it
out of your JAR's dependencies.
```xml
<project>
@@ -68,20 +71,22 @@ This POM adds a dependency on Checkstyle.
<version>1.0</version>
<dependencies>
<dependency>
- <groupId>checkstyle</groupId>
+ <groupId>com.puppycrawl.tools</groupId>
<artifactId>checkstyle</artifactId>
- <version>${project.version}</version>
+ <version>${checkstyleVersion}</version>
+ <scope>provided</scope>
</dependency>
</dependencies>
</project>
```
-#[[### `packagenames.xml`]]#
+<a id="packagenames.xml"></a>
-This file lets you specify the names of the packages that you want to use.
-This example adds `com.mycompany.checks` to the standard set of Checkstyle
packages.
-You can then use your custom checks in the Checkstyle configuration file.
-You do not need to specify their package name.
+#[[### `checkstyle_packages.xml`]]#
+
+Checkstyle reads every `checkstyle_packages.xml` file at the root of the
classpath.
+This one adds `com.mycompany.checks` to the packages that Checkstyle searches
for modules.
+You can then use your checks in the Checkstyle configuration without their
package name.
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -92,80 +97,76 @@ You do not need to specify their package name.
<checkstyle-packages>
<package name="com.mycompany.checks"/>
- <package name="com.puppycrawl.tools.checkstyle">
- <package name="checks">
- <package name="blocks"/>
- <package name="coding"/>
- <package name="design"/>
- <package name="duplicates"/>
- <package name="header"/>
- <package name="imports"/>
- <package name="indentation"/>
- <package name="j2ee"/>
- <package name="javadoc"/>
- <package name="metrics"/>
- <package name="modifier"/>
- <package name="naming"/>
- <package name="sizes"/>
- <package name="whitespace"/>
- </package>
- <package name="filters"/>
- </package>
</checkstyle-packages>
```
#[[### `MethodLimitCheck.java`]]#
Here is the example check from the Checkstyle site.
-It checks that your source files do not have more than 30 methods.
+It checks that a class or interface does not have more than 30 methods.
+The `max` property can change the limit.
```java
package com.mycompany.checks;
-import com.puppycrawl.tools.checkstyle.api.*;
-public class MethodLimitCheck extends Check
-{
+import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
+import com.puppycrawl.tools.checkstyle.api.DetailAST;
+import com.puppycrawl.tools.checkstyle.api.TokenTypes;
+
+public class MethodLimitCheck extends AbstractCheck {
+
private int max = 30;
- public int[] getDefaultTokens()
- {
- return new int[]{TokenTypes.CLASS_DEF, TokenTypes.INTERFACE_DEF};
+ public void setMax(int max) {
+ this.max = max;
}
- public void visitToken(DetailAST ast)
- {
+ @Override
+ public int[] getDefaultTokens() {
+ return new int[] {TokenTypes.CLASS_DEF, TokenTypes.INTERFACE_DEF};
+ }
+
+ @Override
+ public int[] getAcceptableTokens() {
+ return getDefaultTokens();
+ }
+
+ @Override
+ public int[] getRequiredTokens() {
+ return new int[0];
+ }
+
+ @Override
+ public void visitToken(DetailAST ast) {
// find the OBJBLOCK node below the CLASS_DEF/INTERFACE_DEF
DetailAST objBlock = ast.findFirstToken(TokenTypes.OBJBLOCK);
- // count the number of direct children of the OBJBLOCK
- // that are METHOD_DEFS
+ // count the number of direct children of the OBJBLOCK that are
METHOD_DEFs
int methodDefs = objBlock.getChildCount(TokenTypes.METHOD_DEF);
- // report error if limit is reached
+ // report a violation if the limit is exceeded
if (methodDefs > max) {
- log(ast.getLineNo(),
- "too many methods, only " + max + " are allowed");
+ log(ast, "too many methods, only " + max + " are allowed");
}
- }
+ }
}
```
+<a id="Building_a_JAR_for_your_custom_checks_project"></a>
+
Build the JAR for Your Custom Checks Project
--------------------------------------------
-To use your custom checks in other projects, package and install them.
-Run this command:
+To use your custom checks in other projects, package and install them:
```shell
mvn install
```
-This command produces a JAR file with these contents.
-It also installs the file into your local repository.
+This command builds a JAR file with these contents and installs it into your
local repository.
#[[### `mycompany-checkstyle-checks-1.0.jar`]]#
```text
mycompany-checkstyle-checks-1.0.jar
-|-- pom.xml
|-- META-INF
| |-- MANIFEST.MF
| `-- maven
@@ -173,13 +174,15 @@ mycompany-checkstyle-checks-1.0.jar
| `-- mycompany-checkstyle-checks
| |-- pom.xml
| `-- pom.properties
+|-- checkstyle_packages.xml
`-- com
`-- mycompany
`-- checks
- |-- packagenames.xml
`-- MethodLimitCheck.class
```
+<a id="Using_your_checks_in_another_project"></a>
+
Use Your Checks in Another Project
----------------------------------
@@ -187,22 +190,22 @@ You are now ready to use your custom checks in another
project.
#[[### Create a Checkstyle configuration]]#
-Create the file `checkstyle.xml` in the root of the project that wants to use
your custom checks.
-In this file, tell Checkstyle which checks you want to use.
-
-**Note:** You do not have to specify the fully qualified class name of your
check here.
-The `packagenames.xml` file makes this possible.
+Create the file `checkstyle.xml` in the root of the project that uses your
custom checks.
+In this file, tell Checkstyle which checks to run.
+Thanks to `checkstyle_packages.xml`, `MethodLimit` is enough; you do not need
the fully qualified class name.
```xml
-<?xml version="1.0" ?>
+<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
- "-//Checkstyle//DTD Checkstyle Configuration 1.2//EN"
- "https://checkstyle.org/dtds/configuration_1_2.dtd">
+ "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+ "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="TreeWalker">
- <module name="MethodLimit"/>
+ <module name="MethodLimit">
+ <property name="max" value="20"/>
+ </module>
</module>
</module>
```
@@ -212,10 +215,9 @@ The `packagenames.xml` file makes this possible.
Finally, tell the other project to use your custom Checkstyle checks.
Add this configuration to the `pom.xml` of that project.
-**Note:** You must specify a plugin dependency on
`mycompany-checkstyle-checks` in the `<build>` element of your `pom.xml`.
-This dependency will not work in the `<reporting>` element.
-The `<reporting>` element does not support plugin dependencies.
-Do the rest of the configuration in the normal way in the `<reporting>`
element.
+**Note:** Declare the plugin dependency on `mycompany-checkstyle-checks` in
the `<build>` section of your `pom.xml`.
+The `<reporting>` section does not support plugin dependencies, but the report
uses the ones declared in `<build>`.
+Do the rest of the configuration in the normal way in the `<reporting>`
section.
```xml
<project>
@@ -251,3 +253,10 @@ Do the rest of the configuration in the normal way in the
`<reporting>` element.
...
</project>
```
+
+Run `mvn site` for the report, or `mvn checkstyle:check
-Dcheckstyle.config.location=checkstyle.xml` to check from the command line.
+With `max` set to `2`, a class with three methods logs:
+
+```text
+[ERROR] src/main/java/com/example/Big.java:[3,1] (extension) MethodLimit: too
many methods, only 2 are allowed
+```
diff --git a/src/site/markdown/examples/custom-property-expansion.md.vm
b/src/site/markdown/examples/custom-property-expansion.md.vm
index 4c35d21..21fb99f 100644
--- a/src/site/markdown/examples/custom-property-expansion.md.vm
+++ b/src/site/markdown/examples/custom-property-expansion.md.vm
@@ -23,6 +23,8 @@ specific language governing permissions and limitations
under the License.
-->
+<a id="Using_Custom_Checkstyle_Property_Expansion_Definitions"></a>
+
# Custom Checkstyle Property Expansion Definitions
You can define custom [property expansion
definitions](https://checkstyle.org/config.html#Properties) for the Checker.
@@ -45,7 +47,7 @@ It also lets the Checker users specify their own projectname.
<module name="TreeWalker">
<module name="PackageName">
<property name="format"
- value="com\.example\.$\{projectname\}(\.[a-z][a-zA-Z0-9]+)*$"/>
+
value="com\.example\.${esc.dollar}{projectname}(\.[a-z][a-zA-Z0-9]+)*$"/>
</module>
</module>
</module>
@@ -78,7 +80,7 @@ Checkstyle uses it when it encounters the variable in the
Checker configuration
```
You can also provide the property expansion information from a location with
the `propertiesLocation` parameter as shown below.
-The parameter can point to a URL, a file, or a build classpath resource.
+The parameter can point to a file relative to the project directory, a URL, or
a resource on the plugin classpath.
```xml
<project>
@@ -91,7 +93,7 @@ The parameter can point to a URL, a file, or a build
classpath resource.
<version>${project.version}</version>
<configuration>
<configLocation>checkstyle.xml</configLocation>
-
<propertiesLocation>${basedir}/checkstyle.properties</propertiesLocation>
+ <propertiesLocation>checkstyle.properties</propertiesLocation>
</configuration>
</plugin>
</plugins>
diff --git a/src/site/markdown/examples/inline-checker-config.md.vm
b/src/site/markdown/examples/inline-checker-config.md.vm
index eef312b..3da40ce 100644
--- a/src/site/markdown/examples/inline-checker-config.md.vm
+++ b/src/site/markdown/examples/inline-checker-config.md.vm
@@ -23,15 +23,14 @@ specific language governing permissions and limitations
under the License.
-->
-# Inline Checkstyle Checker Configuration
+<a id="Using_an_Inline_Checkstyle_Checker_Configuration"></a>
-From version 2.12, you can define an inline [Checker
configuration](https://checkstyle.org/config.html#Checker) directly in the
`configuration` section of the plugin inside your `pom.xml`.
+# Inline Checkstyle Checker Configuration
-This is useful when you want to run the Checkstyle checks with every compile.
-You do not need to create a separate project for your Checkstyle rules.
-You do not need a separate parent POM structure.
+You can define a [Checker
configuration](https://checkstyle.org/config.html#Checker) directly in the
`<configuration>` section of the plugin in your `pom.xml`.
+You then need no separate ruleset file, no separate project for your
Checkstyle rules, and no parent POM structure.
-Use the `checkstyleRules` parameter to define a custom Checkstyle checker
configuration inside your `pom.xml`.
+Use the `checkstyleRules` parameter to define the checker configuration inside
your `pom.xml`:
```xml
<project>
@@ -56,15 +55,15 @@ Use the `checkstyleRules` parameter to define a custom
Checkstyle checker config
<checkstyleRules>
<module name="Checker">
- <!-- Checks for Size Violations. -->
- <!-- See http://checkstyle.sf.net/config_sizes.html -->
+ <!-- Checks for size violations. -->
+ <!-- See https://checkstyle.org/checks/sizes/ -->
<module name="FileLength">
<property name="max" value="3500" />
<property name="fileExtensions" value="java"/>
</module>
- <!-- Checks for whitespace -->
- <!-- See http://checkstyle.sf.net/config_whitespace.html -->
+ <!-- Checks for whitespace. -->
+ <!-- See https://checkstyle.org/checks/whitespace/ -->
<module name="FileTabCharacter"/>
<module name="TreeWalker">
@@ -83,77 +82,33 @@ Use the `checkstyleRules` parameter to define a custom
Checkstyle checker config
</project>
```
-# Different Header
-
-The plugin writes the inline configuration to a file.
-It then passes the file to checkstyle.
-The configuration file must contain a specific
[header](https://checkstyle.org/config.html#Configuration_XML_Structure).
+<a id="Using_a_different_header"></a>
-The plugin includes one by default.
-The default header is compatible with the included checkstyle version.
+${esc.h}${esc.h} Different Header
-When you use a different checkstyle version than the one that is included, you
must specify a different header:
+The plugin writes the inline configuration to `target/checkstyle-checker.xml`
and passes that file to Checkstyle.
+The file starts with a [document type
declaration](https://checkstyle.org/config.html#Configuration_XML_Structure),
which the plugin adds for you.
+The default declaration references the Checkstyle configuration DTD 1.3:
```xml
-<project>
- ...
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-checkstyle-plugin</artifactId>
- <version>${project.version}</version>
- <executions>
- <execution>
- <id>verify-style</id>
- <phase>process-classes</phase>
- <goals>
- <goal>check</goal>
- </goals>
- </execution>
- </executions>
- <configuration>
- <logViolationsToConsole>true</logViolationsToConsole>
- <checkstyleRules>
- <module name="Checker">
-
- <!-- Checks for Size Violations. -->
- <!-- See http://checkstyle.sf.net/config_sizes.html -->
- <module name="FileLength">
- <property name="max" value="3500" />
- <property name="fileExtensions" value="java"/>
- </module>
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+ "https://checkstyle.org/dtds/configuration_1_3.dtd">
+```
- <!-- Checks for whitespace -->
- <!-- See http://checkstyle.sf.net/config_whitespace.html -->
- <module name="FileTabCharacter"/>
+DTD 1.3 is the current version, and the default works when you [upgrade
Checkstyle at runtime](./upgrading-checkstyle.html).
+Set the `checkstyleRulesHeader` parameter only if you need a different
declaration:
- <module name="TreeWalker">
- <module name="StaticVariableName"/>
- <module name="TypeName">
- <property name="format" value="^_?[A-Z][a-zA-Z0-9]*$"/>
- </module>
- </module>
- </module>
- </checkstyleRules>
- <checkstyleRulesHeader>
-<![CDATA[
-<!DOCTYPE module PUBLIC
- "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
- "https://checkstyle.org/dtds/configuration_1_3.dtd">
+```xml
+<configuration>
+ <checkstyleRules>
+ ...
+ </checkstyleRules>
+ <checkstyleRulesHeader>
+<![CDATA[<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+ "https://checkstyle.org/dtds/configuration_1_3.dtd">
]]>
- </checkstyleRulesHeader>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>com.puppycrawl.tools</groupId>
- <artifactId>checkstyle</artifactId>
- <version>8.15</version>
- </dependency>
- </dependencies>
- </plugin>
- </plugins>
- </build>
- ...
-</project>
+ </checkstyleRulesHeader>
+</configuration>
```
diff --git a/src/site/markdown/examples/multi-module-config.md.vm
b/src/site/markdown/examples/multi-module-config.md.vm
index 3407633..f97b08d 100644
--- a/src/site/markdown/examples/multi-module-config.md.vm
+++ b/src/site/markdown/examples/multi-module-config.md.vm
@@ -25,10 +25,8 @@ under the License.
# Multimodule Configuration
-From version 2.12 of this Plugin, you can
[inline](./inline-checker-config.html) the configuration directly in the parent
POM.
-
-You can configure the Checkstyle Plugin for large multimodule projects.
-It requires some setup.
+To share one Checkstyle configuration across the modules of a large project,
put it in a JAR and add that JAR as a plugin dependency.
+For a small set of rules, you can instead
[inline](./inline-checker-config.html) the configuration in the parent POM.
This example uses a sample project called _whizbang_.
The project has the structure below:
@@ -63,7 +61,7 @@ whizbang
| | `-- resources
| | `-- whizbang
| | |-- checkstyle.xml
-| | `-- LICENSE.TXT
+| | `-- LICENSE.txt
| `-- pom.xml
|-- core
|-- gui
@@ -141,14 +139,14 @@ Do the rest of the configuration in the normal way in the
`<reporting>` element.
</project>
```
-Make sure that you do not include the Maven Checkstyle Plugin in your
submodules.
-A submodule definition overrides the top level parent POM definition.
+Keep the Checkstyle Plugin configuration in the parent POM only.
+If a submodule declares the plugin as well, its settings override the parent's
for that submodule.
The plugin resolves the values of `configLocation` and `headerLocation` from
the classpath.
The _build-tools_ JAR is in the classpath.
You declared the JAR as a dependency to the plugin.
-Then run a build of the site:
+Then build the site:
```shell
mvn site
diff --git a/src/site/markdown/examples/suppressions-filter.md.vm
b/src/site/markdown/examples/suppressions-filter.md.vm
index 0a9c0a0..de3e05b 100644
--- a/src/site/markdown/examples/suppressions-filter.md.vm
+++ b/src/site/markdown/examples/suppressions-filter.md.vm
@@ -23,11 +23,13 @@ specific language governing permissions and limitations
under the License.
-->
+<a id="Using_a_Suppressions_Filter"></a>
+
# Suppressions Filter
Checkstyle lets you define a list of files and their line ranges.
Checkstyle does not report violations in these ranges.
-This list is called a [suppressions
filter](https://checkstyle.org/config.html#Filters).
+This list is called a [suppressions
filter](https://checkstyle.org/filters/suppressionfilter.html).
Example: `checkstyle-suppressions.xml`
@@ -35,8 +37,8 @@ Example: `checkstyle-suppressions.xml`
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
- "-//Checkstyle//DTD SuppressionFilter Configuration 1.0//EN"
- "https://checkstyle.org/dtds/suppressions_1_0.dtd">
+ "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
+ "https://checkstyle.org/dtds/suppressions_1_2.dtd">
<suppressions>
<suppress checks="JavadocStyleCheck"
@@ -62,7 +64,6 @@ Example: `pom.xml` - This configuration specifies the
suppressions filter for Ch
<configuration>
<configLocation>checkstyle.xml</configLocation>
<suppressionsLocation>checkstyle-suppressions.xml</suppressionsLocation>
-
<suppressionsFileExpression>checkstyle.suppressions.file</suppressionsFileExpression>
</configuration>
</plugin>
</plugins>
@@ -70,3 +71,7 @@ Example: `pom.xml` - This configuration specifies the
suppressions filter for Ch
...
</project>
```
+
+The plugin applies the suppressions file itself, so `checkstyle.xml` needs no
`SuppressionFilter` module.
+The plugin also passes the path of the file to Checkstyle in the
`checkstyle.suppressions.file` property.
+If your Checkstyle configuration refers to the file under another property
name, set that name with the `suppressionsFileExpression` parameter.
diff --git a/src/site/markdown/examples/upgrading-checkstyle.md.vm
b/src/site/markdown/examples/upgrading-checkstyle.md.vm
index 58f99c4..17ac1f8 100644
--- a/src/site/markdown/examples/upgrading-checkstyle.md.vm
+++ b/src/site/markdown/examples/upgrading-checkstyle.md.vm
@@ -23,14 +23,16 @@ specific language governing permissions and limitations
under the License.
-->
+<a id="Upgrading_Checkstyle_at_Runtime"></a>
+
# Upgrade Checkstyle at Runtime
The Maven Checkstyle Plugin has a default Checkstyle version.
For `maven-checkstyle-plugin ${project.version}`, the plugin uses Checkstyle
${checkstyleVersion} by default.
-Checkstyle keeps good compatibility between versions.
-You can override the version used at runtime.
-This lets you use the [latest Checkstyle bug
fixes](https://checkstyle.org/releasenotes.html):
+You can override the version used at runtime with a plugin dependency.
+This lets you use the [latest Checkstyle checks and bug
fixes](https://checkstyle.org/release-notes.html).
+Declare it in `<pluginManagement>` so that it applies both to the `check` goal
and to the reports:
```xml
<project>
@@ -56,3 +58,15 @@ This lets you use the [latest Checkstyle bug
fixes](https://checkstyle.org/relea
...
</project>
```
+
+Newer Checkstyle versions need a newer Java version than the plugin itself.
+Run Maven with a JDK that the chosen Checkstyle version supports:
+
+| Checkstyle | Minimum Java |
+|:---|:---|
+| 10.x | 11 |
+| 11.x and 12.x | 17 |
+| 13.x and later | 21 |
+
+The predefined `sun_checks.xml` and `google_checks.xml` rulesets come from the
Checkstyle JAR.
+When you upgrade Checkstyle, they change with it and can report new violations.
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index ac60f6c..dea24b2 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -25,7 +25,7 @@ under the License.
# Frequently Asked Questions
-1. [Where is `config/maven_checks.xml` predefined
ruleset?](#Where_is_maven_checks.xml_predefined_ruleset)
+1. [Where is the `config/maven_checks.xml` predefined
ruleset?](#Where_is_maven_checks.xml_predefined_ruleset)
1. [How are the Checkstyle properties
set?](#How_are_the_Checkstyle_properties_set)
1. [How do I set a custom ruleset?](#How_do_I_set_a_custom_ruleset)
1. [How do I include the test directory in
Checkstyle?](#How_do_I_include_the_test_directory_in_Checkstyle)
@@ -35,39 +35,38 @@ under the License.
### Where is the `config/maven_checks.xml` predefined ruleset?
-From maven-checkstyle-plugin version 2.14, `config/maven_checks.xml`
-is no longer part of the plugin.
-The file moved to [Apache Maven Shared
Resources](/shared/maven-shared-resources/).
+Version 2.14 removed `config/maven_checks.xml` from the plugin.
+The ruleset is now in [Apache Maven Shared
Resources](/shared/maven-shared-resources/).
+The plugin ships `sun_checks.xml` and `google_checks.xml`; the [Predefined
Rulesets](./config/index.html) page lists the rulesets of each plugin version.
<a id="How_are_the_Checkstyle_properties_set"></a>
### How are the Checkstyle properties set?
-You can set the Checkstyle properties with the `propertiesLocation` parameter
in the
-plugin configuration of your POM.
-The plugin resolves the properties file from the value of the parameter.
+Set them with the `propertyExpansion` parameter, or put them in a properties
file and point the `propertiesLocation` parameter to it.
+See [Custom Checkstyle Property Expansion
Definitions](./examples/custom-property-expansion.html).
<a id="How_do_I_set_a_custom_ruleset"></a>
### How do I set a custom ruleset?
-You can set a custom ruleset with the `configLocation` plugin parameter.
-If you do not specify a value, the plugin uses the `sun_checks.xml` ruleset.
-This ruleset is bundled with the plugin.
+Set the `configLocation` parameter to a file, a URL, or a resource on the
plugin classpath.
+If you do not set it, the plugin uses the `sun_checks.xml` ruleset that ships
with Checkstyle.
+See [Custom Checkstyle Checker
Configuration](./examples/custom-checker-config.html).
<a id="How_do_I_include_the_test_directory_in_Checkstyle"></a>
### How do I include the test directory in Checkstyle?
-You can include the test directory in the Checkstyle report.
-The `includeTestSourceDirectory` plugin parameter must be `true`.
+Set the `includeTestSourceDirectory` parameter to `true`.
+It is `false` by default, for both the `check` goal and the reports.
+<a
id="What_is_the_difference_between_checkstyle:checkstyle_and_checkstyle:check"></a>
<a
id="What_is_the_difference_between_checkstyle.3Acheckstyle_and_checkstyle.3Acheck"></a>
### What is the difference between checkstyle:checkstyle and checkstyle:check?
-The checkstyle:checkstyle goal is a **reporting** goal.
-It adds a report of Checkstyle violations to the output of the
maven-site-plugin.
-The checkstyle:check goal is an ordinary goal.
-It reports violations to the console.
-It fails the build when there are violations.
+`checkstyle:checkstyle` is a reporting goal.
+It writes an HTML report of Checkstyle violations, as part of the site or on
its own.
+It does not fail the build unless you set `failsOnError` to `true`.
+`checkstyle:check` logs violations to the console and fails the build when
there are violations.
diff --git a/src/site/markdown/history.md.vm b/src/site/markdown/history.md.vm
index b351856..26aa571 100644
--- a/src/site/markdown/history.md.vm
+++ b/src/site/markdown/history.md.vm
@@ -22,43 +22,49 @@
Maven Checkstyle Plugin Releases History
----------------------------------------
-#macro ( release $version )
-<a
href="https://checkstyle.org/releasenotes.html#Release_$version">$version</a>
+#macro ( release $version $page )
+<a href="https://checkstyle.org/${page}.html#Release_$version">$version</a>
#end
-#macro ( releaseOld $version )
-<a
href="https://checkstyle.org/releasenotes_old.html#Release_$version">$version</a>
+#if( $checkstyleVersion.startsWith( "9." ) || $checkstyleVersion.startsWith(
"10." ) )
+#set( $currentNotes = "release-notes-old-8-35-10-26" )
+#else
+#set( $currentNotes = "release-notes" )
#end
<table>
<tr><th>release date</th><th>maven-checkstyle-plugin version</th><th>minimum
Java version</th>
<th>default <a href="https://checkstyle.org/">Checkstyle</a>
version</th></tr>
-<tr><td>$dateFormat.format( $currentDate
)</td><td>${project.version}</td><td>${javaVersion}</td><td>#release(
${checkstyleVersion} )</td></tr>
-<tr><td>2023-05-19</td><td>3.3.0 </td><td rowspan="7"> 8</td><td
rowspan="4">#release( "9.3" )</td></tr>
+<tr><td>$dateFormat.format( $currentDate
)</td><td>${project.version}</td><td>${javaVersion}</td><td>#release(
${checkstyleVersion} $currentNotes )</td></tr>
+<tr><td>2024-10-22</td><td>3.6.0 </td><td rowspan="11"> 8</td><td
rowspan="8">#release( "9.3" "release-notes-old-8-35-10-26" )</td></tr>
+<tr><td>2024-08-19</td><td>3.5.0 </td></tr>
+<tr><td>2024-06-02</td><td>3.4.0 </td></tr>
+<tr><td>2023-10-21</td><td>3.3.1 </td></tr>
+<tr><td>2023-05-19</td><td>3.3.0 </td></tr>
<tr><td>2023-04-18</td><td>3.2.2 </td></tr>
<tr><td>2023-01-06</td><td>3.2.1 </td></tr>
<tr><td>2022-08-20</td><td>3.2.0 </td></tr>
-<tr><td>2021-01-23</td><td>3.1.2 </td> <td
rowspan="2">#release( "8.29" )</td></tr>
+<tr><td>2021-01-23</td><td>3.1.2 </td> <td
rowspan="2">#release( "8.29" "release-notes-old-8-0-8-34" )</td></tr>
<tr><td>2020-02-08</td><td>3.1.1 </td></tr>
-<tr><td>2019-05-20</td><td>3.1.0 </td> <td>#release(
"8.19" )</td></tr>
-<tr><td>2018-01-04</td><td>3.0.0 </td><td rowspan="3"> 7</td><td>#release(
"8.18" )</td></tr>
-<tr><td>2015-10-15</td><td>2.17 </td> <td>#release(
"6.11.2" )</td></tr>
-<tr><td>2015-07-13</td><td>2.16 </td> <td>#release(
"6.2" )</td></tr>
-<tr><td>2015-03-20</td><td>2.15 </td><td> 6</td><td>#release(
"6.1.1" )</td></tr>
-<tr><td>2015-02-05</td><td>2.14 </td><td rowspan="13">5</td><td>#release(
"5.8" ) </td></tr>
-<tr><td>2014-09-18</td><td>2.13 </td> <td
rowspan="3">#releaseOld( "5.7" ) </td></tr>
+<tr><td>2019-05-20</td><td>3.1.0 </td> <td>#release(
"8.19" "release-notes-old-8-0-8-34" )</td></tr>
+<tr><td>2018-01-04</td><td>3.0.0 </td><td rowspan="3"> 7</td><td>#release(
"8.18" "release-notes-old-8-0-8-34" )</td></tr>
+<tr><td>2015-10-15</td><td>2.17 </td> <td>#release(
"6.11.2" "release-notes-old-6-0-7-8" )</td></tr>
+<tr><td>2015-07-13</td><td>2.16 </td> <td>#release(
"6.2" "release-notes-old-6-0-7-8" )</td></tr>
+<tr><td>2015-03-20</td><td>2.15 </td><td> 6</td><td>#release(
"6.1.1" "release-notes-old-6-0-7-8" )</td></tr>
+<tr><td>2015-02-05</td><td>2.14 </td><td rowspan="13">5</td><td>#release(
"5.8" "release-notes-old-1-0-5-9" ) </td></tr>
+<tr><td>2014-09-18</td><td>2.13 </td> <td
rowspan="3">#release( "5.7" "release-notes-old-1-0-5-9" ) </td></tr>
<tr><td>2014-04-19</td><td>2.12.1</td></tr>
<tr><td>2014-03-12</td><td>2.12 </td></tr>
-<tr><td>2013-11-15</td><td>2.11 </td> <td
rowspan="2">#releaseOld( "5.6" ) </td></tr>
+<tr><td>2013-11-15</td><td>2.11 </td> <td
rowspan="2">#release( "5.6" "release-notes-old-1-0-5-9" ) </td></tr>
<tr><td>2013-02-22</td><td>2.10 </td></tr>
-<tr><td>2012-02-25</td><td>2.9.1 </td> <td
rowspan="2">#releaseOld( "5.5" ) </td></tr>
+<tr><td>2012-02-25</td><td>2.9.1 </td> <td
rowspan="2">#release( "5.5" "release-notes-old-1-0-5-9" ) </td></tr>
<tr><td>2012-02-12</td><td>2.9 </td></tr>
-<tr><td>2011-11-01</td><td>2.8 </td> <td
rowspan="2">#releaseOld( "5.4" ) </td></tr>
+<tr><td>2011-11-01</td><td>2.8 </td> <td
rowspan="2">#release( "5.4" "release-notes-old-1-0-5-9" ) </td></tr>
<tr><td>2011-08-11</td><td>2.7 </td></tr>
-<tr><td>2010-09-25</td><td>2.6 </td> <td
rowspan="3">#releaseOld( "5.0" ) </td></tr>
+<tr><td>2010-09-25</td><td>2.6 </td> <td
rowspan="3">#release( "5.0" "release-notes-old-1-0-5-9" ) </td></tr>
<tr><td>2010-02-12</td><td>2.5 </td></tr>
<tr><td>2009-11-18</td><td>2.4 </td></tr>
-<tr><td>2009-07-14</td><td>2.3 </td><td rowspan="4">1.4</td><td
rowspan="2">#releaseOld( "4.4" ) </td></tr>
+<tr><td>2009-07-14</td><td>2.3 </td><td rowspan="4">1.4</td><td
rowspan="2">#release( "4.4" "release-notes-old-1-0-5-9" ) </td></tr>
<tr><td>2008-06-04</td><td>2.2 </td></tr>
-<tr><td>2006-05-14</td><td>2.1 </td> <td
rowspan="2">#releaseOld( "4.1" ) </td></tr>
+<tr><td>2006-05-14</td><td>2.1 </td> <td
rowspan="2">#release( "4.1" "release-notes-old-1-0-5-9" ) </td></tr>
<tr><td>2006-01-28</td><td>2.0 </td></tr>
</table>
diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index b93c967..5ae67a2 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -26,56 +26,73 @@ under the License.
# ${project.name}
-The Checkstyle Plugin generates a report on the code style used by the
developers.
-For more information about Checkstyle, see
[https://checkstyle.org/](https://checkstyle.org/).
+The Checkstyle Plugin runs [Checkstyle](https://checkstyle.org/) on your
project's sources and resources.
+It can fail the build on violations, or add a Checkstyle report to the project
site.
This version of the plugin uses Checkstyle ${checkstyleVersion} by default.
-It requires Java ${javaVersion}.
-You can [upgrade the version used at
runtime](./examples/upgrading-checkstyle.html).
+It requires Maven 3.9.0 or later and Java ${javaVersion} or later.
+You can [use a newer Checkstyle version](./examples/upgrading-checkstyle.html)
at runtime.
-The plugin can be configured in the project's POM.
-This version of the plugin provides two predefined rulesets:
[`sun_checks.xml`](https://checkstyle.org/sun_style.html) and
[`google_checks.xml`](https://checkstyle.org/google_style.html).
-You can also use a custom ruleset in the plugin configuration.
+Quick Start
+-----------
+
+Check the code against the default `sun_checks.xml` ruleset and fail on
violations:
+
+```shell
+mvn checkstyle:check
+```
+
+Check against the Google ruleset instead.
+The `google_checks.xml` ruleset reports at `warning` severity, so also lower
the severity that counts as a violation:
+
+```shell
+mvn checkstyle:check -Dcheckstyle.config.location=google_checks.xml
-Dcheckstyle.violationSeverity=warning
+```
+
+Write an HTML report to `target/reports/checkstyle.html` without failing the
build:
+
+```shell
+mvn checkstyle:checkstyle
+```
+
+To run the check in every build, bind the `check` goal in your POM, as shown
on the [usage page](./usage.html).
+
+The plugin ships two predefined rulesets from Checkstyle:
[`sun_checks.xml`](https://checkstyle.org/sun_style.html) (the default) and
[`google_checks.xml`](https://checkstyle.org/google_style.html).
+You can also [use your own ruleset](./examples/custom-checker-config.html) or
[write it inline in the POM](./examples/inline-checker-config.html).
+Rulesets from older plugin versions are listed on the [Predefined
Rulesets](./config/index.html) page.
Goals Overview
--------------
The Checkstyle Plugin has three goals:
+- [checkstyle:check](./check-mojo.html) performs Checkstyle analysis and logs
violations to the console.
+ It fails the build on violations by default, and binds to the `verify` phase.
+ It can also re-use the result of an earlier `checkstyle:checkstyle` run.
- [checkstyle:checkstyle](./checkstyle-mojo.html) is a reporting goal that
performs Checkstyle analysis and generates a report on violations.
-- [checkstyle:checkstyle-aggregate](./checkstyle-aggregate-mojo.html) is a
reporting goal that performs Checkstyle analysis and generates an aggregate
HTML report on violations in a multi-module reactor build.
-- [checkstyle:check](./check-mojo.html) is a goal that performs Checkstyle
analysis and outputs violations or a count of violations to the console.
- It can also fail the build.
- You can configure it to re-use an earlier analysis.
-
-Major Version Upgrade to version 3.0.0
---------------------------------------
+- [checkstyle:checkstyle-aggregate](./checkstyle-aggregate-mojo.html) is a
reporting goal that generates one report for all modules of a multi-module
build.
+ Run it from the root project.
-These two parameters were removed from the plugin configuration:
-
-- `sourceDirectory`: use `sourceDirectories` instead.
-- `testSourceDirectory`: use `testSourceDirectories` instead.
+[checkstyle:help](./help-mojo.html) lists the goals and their parameters.
Usage
-----
General instructions on how to use the Checkstyle Plugin are on the [usage
page](./usage.html).
-The examples below describe more specific use cases.
-
-If you still have questions about the plugin's usage, look at the
[FAQ](./faq.html).
-You can also contact the [user mailing list](./mailing-lists.html).
-The posts to the mailing list are archived.
-An older thread can contain the answer to your question.
-You can also search the [mail archive](./mailing-lists.html).
-
-If you think that the plugin lacks a feature or has a defect, report it in the
[issue tracker](https://issues.apache.org/jira/projects/MCHECKSTYLE/).
-When you create a new issue, include a comprehensive description of your
concern.
-For bug fixes, the developers must be able to reproduce your problem.
-Attach entire debug logs, POMs, or little demo projects to the issue.
-Patches are welcome.
-
-Contributors can check out the project from the [source
repository](./scm.html).
-They can also find supplementary information in the [guide to helping with
Maven](https://maven.apache.org/guides/development/guide-helping.html).
+The [examples](#Examples) below describe more specific use cases.
+If you still have questions, look at the [FAQ](./faq.html) or ask on the [user
mailing list](./mailing-lists.html).
+
+Report a defect or request a feature in the [issue
tracker](./issue-management.html).
+For a bug, include the steps or a small project that reproduces it.
+The source code is in the [source repository](./scm.html).
+
+<a id="Major_Version_Upgrade_to_version_3.0.0"></a>
+
+Upgrading From 2.x
+------------------
+
+Version 3.0.0 removed the `sourceDirectory` and `testSourceDirectory`
parameters.
+Use `sourceDirectories` and `testSourceDirectories` instead.
Examples
--------
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 7af9f9c..4607781 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -31,90 +31,113 @@ The examples below describe the basic usage of the
Checkstyle Plugin.
Generate Checkstyle Report As Part of the Project Reports
---------------------------------------------------------
-Generate the Checkstyle report as part of the Project Reports.
-Add the Checkstyle Plugin to the `<reporting>` section of your `pom.xml`.
+Add the Checkstyle Plugin to the `<reporting>` section of your `pom.xml`:
```xml
<project>
...
- <reporting>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-checkstyle-plugin</artifactId>
- <version>${project.version}</version>
- <reportSets>
- <reportSet>
- <reports>
- <report>checkstyle</report>
- </reports>
- </reportSet>
- </reportSets>
- </plugin>
- </plugins>
- </reporting>
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-checkstyle-plugin</artifactId>
+ <version>${project.version}</version>
+ </plugin>
+ </plugins>
+ </reporting>
...
</project>
```
-Run the site phase to generate the report.
+Run the `site` phase to generate the report in `target/site/checkstyle.html`:
```shell
mvn site
```
+In a multi-module build, you can add one report for all modules with the
`checkstyle-aggregate` report.
+List the reports you want in a `<reportSet>`:
+
+```xml
+<project>
+ ...
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-checkstyle-plugin</artifactId>
+ <version>${project.version}</version>
+ <reportSets>
+ <reportSet>
+ <reports>
+ <report>checkstyle</report>
+ <report>checkstyle-aggregate</report>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ </plugins>
+ </reporting>
+ ...
+</project>
+```
+
Generate Checkstyle Report As Standalone
----------------------------------------
-You can also generate the Checkstyle report with the `checkstyle:checkstyle`
goal from the command line.
-You do not need to specify the Checkstyle Plugin in your `pom.xml` unless you
need a specific configuration.
+You can also generate the Checkstyle report from the command line.
+You do not need to declare the plugin in your `pom.xml` unless you need a
specific configuration.
```shell
mvn checkstyle:checkstyle
```
-Check for Violations as Part of the Build
------------------------------------------
+The report is written to `target/reports/checkstyle.html`.
+For a multi-module build, run `mvn checkstyle:checkstyle-aggregate` from the
root project; it writes `target/reports/checkstyle-aggregate.html`.
-If you want the console report or a build failure, add an execution of
`checkstyle::check` to the `<build>` element.
-Configure any options that you need.
+<a id="Checking_for_Violations_as_Part_of_the_Build"></a>
-Options that you set in the `<reporting>` element do not affect executions in
the `<build>` element.
+Check for Violations as Part of the Build
+-----------------------------------------
-The phase that `checkstyle::check` is bound to is important.
-If you bind it to the validate phase, it checks the code before compilation.
-It is guaranteed to run.
-If the code is invalid, the errors that checkstyle reports can differ from the
errors from the javac compiler.
+To log violations to the console and fail the build, add an execution of the
`check` goal to the `<build>` section.
+Options that you set in the `<reporting>` section do not affect executions in
the `<build>` section.
-Another common option binds the goal to the verify phase.
-The verify phase runs much later than the validate phase.
-A later phase lets the javac compiler flag invalid code before checkstyle runs.
+```xml
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-checkstyle-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <configLocation>checkstyle.xml</configLocation>
+ </configuration>
+ <executions>
+ <execution>
+ <id>validate</id>
+ <phase>validate</phase>
+ <goals>
+ <goal>check</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
+```
-If developers run `mvn test` before they push changes, checkstyle does not run.
-The verify phase occurs after the test phase.
+The phase that you bind `check` to matters:
-For example:
+- Bound to `validate`, as above, it runs before compilation, so it also runs
on `mvn compile` and `mvn test`.
+ For code that does not compile, Checkstyle can report different errors than
the `javac` compiler.
+- Without a `<phase>`, it binds to `verify`.
+ The compiler then flags invalid code first, but `mvn test` does not run the
check.
-```xml
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-checkstyle-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <configLocation>checkstyle.xml</configLocation>
- <inputEncoding>UTF-8</inputEncoding>
- <consoleOutput>true</consoleOutput>
- <failsOnError>true</failsOnError>
- <linkXRef>false</linkXRef>
- </configuration>
- <executions>
- <execution>
- <id>validate</id>
- <phase>validate</phase>
- <goals>
- <goal>check</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
-```
+By default, only violations of severity `error` are logged and fail the build.
+Set `violationSeverity` to `warning` to include warnings, or `failOnViolation`
to `false` to log violations without failing.
+To skip the check for one build, pass `-Dcheckstyle.skip`.
diff --git a/src/site/site.xml b/src/site/site.xml
index e66a943..85c510f 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -27,7 +27,7 @@ under the License.
<item name="Usage" href="usage.html"/>
<item name="FAQ" href="faq.html"/>
<!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 -->
- <item name="License" href="http://www.apache.org/licenses/"/>
+ <item name="License" href="https://www.apache.org/licenses/"/>
<item name="Download" href="download.html"/>
<item name="Releases History" href="history.html"/>
</menu>