From 79d8c40f11b4c4025c2f288a7b7f8e2d11c392c2 Mon Sep 17 00:00:00 2001 From: Stephan Schroevers Date: Sat, 8 Apr 2023 15:05:38 +0200 Subject: [PATCH 1/4] Improve contribution documentation - Explicitly mention that users should run `mvn clean install` before opening a pull request. - Introduce a `SECURITY.md` file as suggested by GitHub. --- CONTRIBUTING.md | 5 +++++ README.md | 6 ++++++ SECURITY.md | 23 +++++++++++++++++++++++ 3 files changed, 34 insertions(+) create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1023593a8f..29800117c2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,6 +48,10 @@ be accepted. When in doubt, make sure to first raise an To the extent possible, the pull request process guards our coding guidelines. Some pointers: +- Make sure that the `mvn clean install` build fully passes, ideally before + opening a pull request. See the [development + instructions][error-prone-support-developing] for details on how to + efficiently resolve many of the errors and warnings that may be reported. - Checks should be _topical_: ideally they address a single concern. - Where possible checks should provide _fixes_, and ideally these are completely behavior-preserving. In order for a check to be adopted by users @@ -66,6 +70,7 @@ Some pointers: sneak in unrelated changes; instead just open more than one pull request 😉. [error-prone-criteria]: https://errorprone.info/docs/criteria +[error-prone-support-developing]: https://github.com/PicnicSupermarket/error-prone-support/tree/master#-developing-error-prone-support [error-prone-support-issues]: https://github.com/PicnicSupermarket/error-prone-support/issues [error-prone-support-mutation-tests]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/run-mutation-tests.sh [error-prone-support-pulls]: https://github.com/PicnicSupermarket/error-prone-support/pulls diff --git a/README.md b/README.md index 295e120b4d..2dfc97903c 100644 --- a/README.md +++ b/README.md @@ -228,6 +228,11 @@ Want to report or fix a bug, suggest or add a new feature, or improve the documentation? That's awesome! Please read our [contribution guidelines][contributing]. +### Security + +If you want to report a security vulnerablity, please do so through a private +channel; please see our [security policy][security] for details. + [bug-checks]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/ [bug-checks-identity-conversion]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/IdentityConversion.java [contributing]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/CONTRIBUTING.md @@ -257,3 +262,4 @@ guidelines][contributing]. [refaster-rules]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ [reproducible-builds-badge]: https://img.shields.io/badge/Reproducible_Builds-ok-success?labelColor=1e5b96 [reproducible-builds-report]: https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/tech/picnic/error-prone-support/error-prone-support/README.md +[security]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000000..12d3645733 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,23 @@ +# Security policy + +We take security seriously. We are mindful of Error Prone Support's place in +the software supply chain, and the risks and responsibilities that come with +this. + +## Supported versions + +This project uses [semantic versioning][semantic-versioning]. In general, only +the latest version of this software is supported. That said, if users have a +compelling reason to ask for patch release of an older major release, then we +will seriously consider such a request. We do urge users to stay up-to-date and +use the latest release where feasible. + +## Reporting a vulnerability + +To report a vulnerability, please visit the [security +advisories][security-advisories] page an click _Report a vulnerability_. We +will take such reports seriously and work with you to resolve the issue in a +timely manner. + +[security-advisories]: https://github.com/PicnicSupermarket/error-prone-support/security/advisories +[semantic-versioning]: https://semver.org/ From a6c2227c091973604f000f2c08d88b1b40b1113c Mon Sep 17 00:00:00 2001 From: Stephan Schroevers Date: Sun, 9 Apr 2023 12:07:31 +0200 Subject: [PATCH 2/4] Don't discourage people --- CONTRIBUTING.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29800117c2..1d74846034 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,10 +48,14 @@ be accepted. When in doubt, make sure to first raise an To the extent possible, the pull request process guards our coding guidelines. Some pointers: -- Make sure that the `mvn clean install` build fully passes, ideally before - opening a pull request. See the [development +- Try to make sure that the `mvn clean install` build fully passes, ideally + before opening a pull request. See the [development instructions][error-prone-support-developing] for details on how to efficiently resolve many of the errors and warnings that may be reported. + That said, if you feel that the build fails for invalid or debatable reasons, + or if you're unsure how to best resolve an issue, don't let that discourage + you from opening a PR with a failing build; we can have a look at the issue + together. - Checks should be _topical_: ideally they address a single concern. - Where possible checks should provide _fixes_, and ideally these are completely behavior-preserving. In order for a check to be adopted by users From 40bafebf3ef102fc0bb17a72670a7d6bb29487bb Mon Sep 17 00:00:00 2001 From: Rick Ossendrijver Date: Tue, 11 Apr 2023 08:40:21 +0200 Subject: [PATCH 3/4] Suggestion for the selfcheck and typos --- CONTRIBUTING.md | 5 +++++ SECURITY.md | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d74846034..87f8159663 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,6 +66,10 @@ Some pointers: checks][error-prone-criteria]. Most guidelines described there apply to this project as well, except that this project _does_ focus quite heavy on style enforcement. But that just makes the previous point doubly important. +- Make sure that there are no violations of the newly introduced checks in the + codebase itself by running the [self check][error-prone-support-self-check]. + See the [development instructions][error-prone-support-developing] for extra + context. - Make sure that a check's [(mutation) test coverage][error-prone-support-mutation-tests] is or remains about as high as it can be. Not only does this lead to better tests, it also points out @@ -78,3 +82,4 @@ Some pointers: [error-prone-support-issues]: https://github.com/PicnicSupermarket/error-prone-support/issues [error-prone-support-mutation-tests]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/run-mutation-tests.sh [error-prone-support-pulls]: https://github.com/PicnicSupermarket/error-prone-support/pulls +[error-prone-support-self-check]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/apply-error-prone-suggestions.sh diff --git a/SECURITY.md b/SECURITY.md index 12d3645733..4a911ad27c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -15,9 +15,9 @@ use the latest release where feasible. ## Reporting a vulnerability To report a vulnerability, please visit the [security -advisories][security-advisories] page an click _Report a vulnerability_. We +advisories][security-advisories] page and click _Report a vulnerability_. We will take such reports seriously and work with you to resolve the issue in a timely manner. [security-advisories]: https://github.com/PicnicSupermarket/error-prone-support/security/advisories -[semantic-versioning]: https://semver.org/ +[semantic-versioning]: https://semver.org From f00ad897a35e724338e7e682640ae0cd21df1bd2 Mon Sep 17 00:00:00 2001 From: Stephan Schroevers Date: Wed, 12 Apr 2023 08:30:13 +0200 Subject: [PATCH 4/4] Proposal --- CONTRIBUTING.md | 24 ++++++++++++------------ README.md | 39 ++++++++++++++++++++++++++++----------- run-full-build.sh | 21 +++++++++++++++++++++ 3 files changed, 61 insertions(+), 23 deletions(-) create mode 100755 run-full-build.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 87f8159663..558292f502 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,14 +48,17 @@ be accepted. When in doubt, make sure to first raise an To the extent possible, the pull request process guards our coding guidelines. Some pointers: -- Try to make sure that the `mvn clean install` build fully passes, ideally - before opening a pull request. See the [development +- Try to make sure that the + [`./run-full-build.sh`][error-prone-support-full-build] script completes + successfully, ideally before opening a pull request. See the [development instructions][error-prone-support-developing] for details on how to - efficiently resolve many of the errors and warnings that may be reported. - That said, if you feel that the build fails for invalid or debatable reasons, - or if you're unsure how to best resolve an issue, don't let that discourage - you from opening a PR with a failing build; we can have a look at the issue - together. + efficiently resolve many of the errors and warnings that may be reported. (In + particular, make sure to run `mvn fmt:format` and + [`./apply-error-prone-suggestions.sh`][error-prone-support-patch].) That + said, if you feel that the build fails for invalid or debatable reasons, or + if you're unsure how to best resolve an issue, don't let that discourage you + from opening a PR with a failing build; we can have a look at the issue + together! - Checks should be _topical_: ideally they address a single concern. - Where possible checks should provide _fixes_, and ideally these are completely behavior-preserving. In order for a check to be adopted by users @@ -66,10 +69,6 @@ Some pointers: checks][error-prone-criteria]. Most guidelines described there apply to this project as well, except that this project _does_ focus quite heavy on style enforcement. But that just makes the previous point doubly important. -- Make sure that there are no violations of the newly introduced checks in the - codebase itself by running the [self check][error-prone-support-self-check]. - See the [development instructions][error-prone-support-developing] for extra - context. - Make sure that a check's [(mutation) test coverage][error-prone-support-mutation-tests] is or remains about as high as it can be. Not only does this lead to better tests, it also points out @@ -79,7 +78,8 @@ Some pointers: [error-prone-criteria]: https://errorprone.info/docs/criteria [error-prone-support-developing]: https://github.com/PicnicSupermarket/error-prone-support/tree/master#-developing-error-prone-support +[error-prone-support-full-build]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/run-full-build.sh [error-prone-support-issues]: https://github.com/PicnicSupermarket/error-prone-support/issues [error-prone-support-mutation-tests]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/run-mutation-tests.sh +[error-prone-support-patch]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/apply-error-prone-suggestions.sh [error-prone-support-pulls]: https://github.com/PicnicSupermarket/error-prone-support/pulls -[error-prone-support-self-check]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/apply-error-prone-suggestions.sh diff --git a/README.md b/README.md index 2dfc97903c..312ea2ce0b 100644 --- a/README.md +++ b/README.md @@ -171,8 +171,15 @@ rules][refaster-rules]. ## 👷 Developing Error Prone Support This is a [Maven][maven] project, so running `mvn clean install` performs a -full clean build and installs the library to your local Maven repository. Some -relevant flags: +full clean build and installs the library to your local Maven repository. + +Once you've made changes, the build may fail due to a warning or error emitted +by static code analysis. The flags and commands listed below allow you to +suppress or (in a large subset of cases) automatically fix such cases. Make +sure to carefully check the available options, as this can save you significant +amounts of development time! + +Relevant Maven build parameters: - `-Dverification.warn` makes the warnings and errors emitted by various plugins and the Java compiler non-fatal, where possible. @@ -189,19 +196,25 @@ relevant flags: Pending a release of [google/error-prone#3301][error-prone-pull-3301], this flag must currently be used in combination with `-Perror-prone-fork`. -Some other commands one may find relevant: +Other highly relevant commands: - `mvn fmt:format` formats the code using [`google-java-format`][google-java-format]. -- `./run-mutation-tests.sh` runs mutation tests using [Pitest][pitest]. The - results can be reviewed by opening the respective +- [`./run-full-build.sh`][script-run-full-build] builds the project twice, + where the second pass validates compatbility with Picnic's [Error Prone + fork][error-prone-fork-repo] and compliance of the code with any rules + defined within this project. (Consider running this before [opening a pull + request][contributing-pull-request], as the PR checks also perform this + validation.) +- [`./apply-error-prone-suggestions.sh`][script-apply-error-prone-suggestions] + applies Error Prone and Error Prone Support code suggestions to this project. + Before running this command, make sure to have installed the project (`mvn + clean install`) and make sure that the current working directory does not + contain unstaged or uncommited changes. +- [`./run-mutation-tests.sh`][script-run-mutation-tests] runs mutation tests + using [Pitest][pitest]. The results can be reviewed by opening the respective `target/pit-reports/index.html` files. For more information check the [PIT Maven plugin][pitest-maven]. -- `./apply-error-prone-suggestions.sh` applies Error Prone and Error Prone - Support code suggestions to this project. Before running this command, make - sure to have installed the project (`mvn clean install`) and make sure that - the current working directory does not contain unstaged or uncommited - changes. When running the project's tests in IntelliJ IDEA, you might see the following error: @@ -236,6 +249,7 @@ channel; please see our [security policy][security] for details. [bug-checks]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/ [bug-checks-identity-conversion]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/IdentityConversion.java [contributing]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/CONTRIBUTING.md +[contributing-pull-request]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/CONTRIBUTING.md#-opening-a-pull-request [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 @@ -252,8 +266,8 @@ channel; please see our [security policy][security] for details. [maven-central-badge]: https://img.shields.io/maven-central/v/tech.picnic.error-prone-support/error-prone-support?color=blue [maven-central-search]: https://search.maven.org/artifact/tech.picnic.error-prone-support/error-prone-support [maven]: https://maven.apache.org -[picnic-blog]: https://blog.picnic.nl [picnic-blog-ep-post]: https://blog.picnic.nl/picnic-loves-error-prone-producing-high-quality-and-consistent-java-code-b8a566be6886 +[picnic-blog]: https://blog.picnic.nl [pitest]: https://pitest.org [pitest-maven]: https://pitest.org/quickstart/maven [pr-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg @@ -262,4 +276,7 @@ channel; please see our [security policy][security] for details. [refaster-rules]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ [reproducible-builds-badge]: https://img.shields.io/badge/Reproducible_Builds-ok-success?labelColor=1e5b96 [reproducible-builds-report]: https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/tech/picnic/error-prone-support/error-prone-support/README.md +[script-apply-error-prone-suggestions]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/apply-error-prone-suggestions.sh +[script-run-full-build]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/run-full-build.sh +[script-run-mutation-tests]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/run-mutation-tests.sh [security]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/SECURITY.md diff --git a/run-full-build.sh b/run-full-build.sh new file mode 100755 index 0000000000..85177fc8fb --- /dev/null +++ b/run-full-build.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env bash + +# Builds the project twice: once against the original Error Prone release, +# using only Error Prone checks available on Maven Central, and once against +# the Picnic Error Prone fork, additionally enabling all checks defined in this +# project and any Error Prone checks available only from other artifact +# repositories. + +set -e -u -o pipefail + +settings="$(dirname "${0}")/settings.xml" + +mvn clean install \ + -s "${settings}" \ + $@ +mvn clean install \ + -s "${settings}" \ + -Perror-prone-fork \ + -Pnon-maven-central \ + -Pself-check \ + $@