diff --git a/README.md b/README.md index 622065d1c72..f0752a02eeb 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,7 @@ Prone][error-prone-orig-repo] to improve code quality and maintainability. [![Maven Central][maven-central-badge]][maven-central-search] [![GitHub Actions][github-actions-build-badge]][github-actions-build-master] -[![License][license-badge]][license] -[![PRs Welcome][pr-badge]][contributing] +[![License][license-badge]][license] [![PRs Welcome][pr-badge]][contributing] [Getting started](#-getting-started) • [Building](#-building) • [How it works](#-how-it-works) • [Contributing](#%EF%B8%8F-contributing) @@ -28,11 +27,13 @@ Prone][error-prone-orig-repo] to improve code quality and maintainability. ## ⚡ Getting started -This guide assumes Error Prone is already setup in your project. If this is not -the case, please follow their [installation -guide][error-prone-installation-guide]. Next, edit your `pom.xml` file to add -one or more Error Prone Support modules to the `annotationProcessorPaths` of -the `maven-compiler-plugin`: +This library works on top of [Error Prone][error-prone-orig-repo]. + +1. First, follow Error Prone's [installation + guide][error-prone-installation-guide]. + +2. Next, edit your `pom.xml` file to add one or more Error Prone Support + modules to the `annotationProcessorPaths` of the `maven-compiler-plugin`: ```xml @@ -85,6 +86,7 @@ definition. --> This is a [Maven][maven-central] project, so running `mvn clean install` performs a full clean build. Some relevant flags: + - `-Dverification.warn` makes the warnings and errors emitted by various plugins and the Java compiler non-fatal, where possible. - `-Dverification.skip` disables various non-essential plugins and compiles the @@ -101,6 +103,7 @@ performs a full clean build. Some relevant flags: currently be used in combination with `-Perror-prone-fork`. Some other commands one may find relevant: + - `mvn fmt:format` formats the code using [`google-java-format`][google-java-format]. - `./run-mutation-tests.sh` runs mutation tests using [PIT][pitest]. The @@ -123,23 +126,31 @@ implementations. ## ✍️ Contributing Want to report or fix a bug, suggest or add a new feature, or improve the -documentation? That's awesome! Please read [`CONTRIBUTING.md`][contributing]. +documentation? That's awesome! Please read our [contributing +guidelines][contributing]. [contributing]: CONTRIBUTING.md -[error-prone-bugchecker]: https://github.com/google/error-prone/blob/master/check_api/src/main/java/com/google/errorprone/bugpatterns/BugChecker.java +[error-prone-bugchecker]: + https://github.com/google/error-prone/blob/master/check_api/src/main/java/com/google/errorprone/bugpatterns/BugChecker.java [error-prone-fork-jitpack]: https://jitpack.io/#PicnicSupermarket/error-prone [error-prone-fork-repo]: https://github.com/PicnicSupermarket/error-prone -[error-prone-installation-guide]: https://errorprone.info/docs/installation#maven +[error-prone-installation-guide]: + https://errorprone.info/docs/installation#maven [error-prone-orig-repo]: https://github.com/google/error-prone [error-prone-pull-3301]: https://github.com/google/error-prone/pull/3301 -[github-actions-build-badge]: https://github.com/PicnicSupermarket/error-prone-support/actions/workflows/build.yaml/badge.svg -[github-actions-build-master]: https://github.com/PicnicSupermarket/error-prone-support/actions/workflows/build.yaml?query=branch%3Amaster +[github-actions-build-badge]: + https://github.com/PicnicSupermarket/error-prone-support/actions/workflows/build.yaml/badge.svg +[github-actions-build-master]: + https://github.com/PicnicSupermarket/error-prone-support/actions/workflows/build.yaml?query=branch%3Amaster [google-java-format]: https://github.com/google/google-java-format -[license-badge]: https://img.shields.io/github/license/PicnicSupermarket/error-prone-support +[license-badge]: + https://img.shields.io/github/license/PicnicSupermarket/error-prone-support [license]: LICENSE.md -[maven-central-badge]: https://img.shields.io/maven-central/v/tech.picnic.error-prone-support/error-prone-support?color=blue +[maven-central-badge]: + https://img.shields.io/maven-central/v/tech.picnic.error-prone-support/error-prone-support?color=blue [maven-central]: https://maven.apache.org -[maven-central-search]: https://search.maven.org/artifact/tech.picnic.error-prone-support/error-prone-support +[maven-central-search]: + https://search.maven.org/artifact/tech.picnic.error-prone-support/error-prone-support [pitest]: https://pitest.org [pitest-maven]: https://pitest.org/quickstart/maven [pr-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg diff --git a/error-prone-contrib/README.md b/error-prone-contrib/README.md index 616ba56c20f..288d3a42048 100644 --- a/error-prone-contrib/README.md +++ b/error-prone-contrib/README.md @@ -11,23 +11,20 @@ request. ### Building -See [README.md][main-readme]. +See the main [readme][main-readme]. ### Contribution guidelines -See [CONTRIBUTING.md][main-contributing]. +See our [contributing guidelines][main-contributing]. ### Our wishlist We expect the following tasks to help improve the quality of this open source project: -- Document how to enable the checks. - Document how to apply patches. - Document each of the checks. - Add [SonarQube][sonarcloud] and [Codecov][codecov] integrations. -- Investigate whether it makes sense to include license headers in each file. If - so, set that up and enforce it. - Add non-Java file formatting support, like we have internally at Picnic. (I.e., somehow open-source that stuff.) - Auto-generate a website listing each of the checks, just like the Error Prone @@ -47,7 +44,7 @@ project: - Improve an existing check (see `XXX`-marked comments in the code) or write a new one (see the list of suggestions below). -### Ideas for new checks +### Bugchec extension ideas The following is a list of checks we'd like to see implemented: @@ -72,12 +69,13 @@ The following is a list of checks we'd like to see implemented: code and Javadoc `@link` references. - A check which simplifies array expressions. It would replace empty array expressions of the form `new int[] {}` with `new int[0]`. Statements of the - form `byte[] arr = new byte[] {'c'};` would be shortened to `byte[] arr = - {'c'};`. -- A check which replaces expressions of the form `String.format("some prefix - %s", arg)` with `"some prefix " + arg`, and similar for simple suffixes. Can - perhaps be generalized further, though it's unclear how far. (Well, a - `String.format` call without arguments can certainly be simplified, too.) + form `byte[] arr = new byte[] {'c'};` would be shortened to + `byte[] arr = {'c'};`. +- A check which replaces expressions of the form + `String.format("some prefix %s", arg)` with `"some prefix " + arg`, and + similar for simple suffixes. Can perhaps be generalized further, though it's + unclear how far. (Well, a `String.format` call without arguments can + certainly be simplified, too.) - A check which replaces single-character strings with `char`s where possible. For example as argument to `StringBuilder.append` and in string concatenations. @@ -122,11 +120,11 @@ The following is a list of checks we'd like to see implemented: - A check which flags imports from other test classes. - A Guava-specific check which replaces `Joiner.join` calls with `String.join` calls in those cases where the latter is a proper substitute for the former. -- A Guava-specific check which flags `{Immutable,}Multimap` type usages - where `{Immutable,}{List,Set}Multimap` would be more appropriate. -- A Guava-specific check which rewrites `if (conditional) { throw new - IllegalArgumentException(); }` and variants to an equivalent `checkArgument` - statement. Idem for other exception types. +- A Guava-specific check which flags `{Immutable,}Multimap` type usages where + `{Immutable,}{List,Set}Multimap` would be more appropriate. +- A Guava-specific check which rewrites + `if (conditional) { throw new IllegalArgumentException(); }` and variants to + an equivalent `checkArgument` statement. Idem for other exception types. - A Guava-specific check which replaces simple anonymous `CacheLoader` subclass declarations with `CacheLoader.from(someLambda)`. - A Spring-specific check which enforces that methods with the `@Scheduled` @@ -214,16 +212,16 @@ Refaster's expressiveness: - Some Refaster refactorings (e.g. when dealing with lazy evaluation) are valid only when some free parameter is a constant, variable reference or some other pure expression. Introduce a way to express such a constraint. For example, - rewriting `optional1.map(Optional::of).orElse(optional2)` to `optional1.or(() - -> optional2)` is not behavior preserving if evaluation of `optional2` has - side-effects. + rewriting `optional1.map(Optional::of).orElse(optional2)` to + `optional1.or(() -> optional2)` is not behavior preserving if evaluation of + `optional2` has side-effects. - Similarly, certain refactoring operations are only valid if one of the matches expressions is not `@Nullable`. It'd be nice to be able to express this. - Generalize `@Placeholder` support such that rules can reference e.g. "any concrete unary method". This would allow refactorings such as - `Mono.just(constant).flatmap(this::someFun)` -> `Mono.defer(() -> - someFun(constant))`. + `Mono.just(constant).flatmap(this::someFun)` -> + `Mono.defer(() -> someFun(constant))`. - Sometimes a Refaster refactoring can cause the resulting code not to compile due to a lack of generic type information. Identify and resolve such occurrences. For example, an `@AfterTemplate` may require the insertion of a @@ -279,7 +277,8 @@ Refaster's expressiveness: [autorefactor]: https://autorefactor.org [bettercodehub]: https://bettercodehub.com -[checkstyle-external-project-tests]: https://github.com/checkstyle/checkstyle/blob/master/wercker.yml +[checkstyle-external-project-tests]: + https://github.com/checkstyle/checkstyle/blob/master/wercker.yml [codecov]: https://codecov.io [error-prone-bug-patterns]: https://errorprone.info/bugpatterns [error-prone-repo]: https://github.com/google/error-prone