Introduce `{CONTRIBUTING,LICENSE,README}.md` and Error Prone Support's logo #212

japborst · 2022-08-24T07:45:54Z

Suggested commit message:

Set up the project's readme, contributing guidelines, license, and introduce its logo.

japborst · 2022-08-24T07:47:36Z

error-prone-contrib/README.md

-When loading the project in IntelliJ IDEA (and perhaps other IDEs) errors about
-the inaccessibility of `com.sun.tools.javac.*` classes may be reported. If this
-happens, configure your IDE to enable the `add-exports` profile.
+See [README.md][main-readme].


Here and below is duplicate now, therefore linking to the new location. The rest of this content's page should find a better home, but I considered that outside the scope of this PR.

ferdinand-swoboda

Drive by comment: We should put a medium complexity but common before-vs-after use case at the top of the readme so that it's immediately visible what transformations this software enables.

japborst · 2022-08-24T09:45:56Z

We should put a medium complexity but common before-vs-after use case at the top of the readme so that it's immediately visible what transformations this this software enables.

Indeed. The plan was to add usage samples and check samples (to get started for contributions) in a follow-up PR. However, suggestions on this PR are welcome.

rickie

Did a first pass, this looks really cool man. Thanks for all the effort and working on these changes! Love the logo ❤️:smile:!

rickie · 2022-08-24T07:47:05Z

README.md

+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="logo-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="logo.svg">
+  <img alt="Error Prone Support logo'" src="logo.svg" width="50%">


Suggested change

<img alt="Error Prone Support logo'" src="logo.svg" width="50%">

<img alt="Error Prone Support logo" src="logo.svg" width="50%">

README.md

rickie · 2022-08-25T13:42:09Z

README.md

+[google-java-format]: https://github.com/google/google-java-format
+[licence-badge]:
+  https://img.shields.io/github/license/PicnicSupermarket/error-prone-support
+[licence]: LICENSE.md


Suggested change

[licence]: LICENSE.md

[license]: LICENSE.md

README.md

rickie · 2022-08-25T14:21:27Z

README.md

+Error Prone Support is a Picnic-opinionated extension of [Error
+Prone][error-prone-repo] to improve code quality and maintainability.
+
+> Error Prone is a static analysis tool for Java that catches common programming


Do we want to show, in a way, that this is a quote from errorprone.info?

I linked @google/error-prone above (as [error-prone-repo]), which is also where this comes from. Would be enough, I think :)

README.md

Stephan202

Added a commit.

Shall we also enable Github Discussions? If so, we should reference it somewhere.

Didn't approve yet because I might want to do another pass later.

LICENSE.md

Stephan202 · 2022-08-28T11:49:24Z

README.md

+[error-prone-installation-guide]. Next, edit your `pom.xml` file to add Error
+Prone Support to your project. See [@PicnicSupermarket/oss-parent/pom.xml]
+[oss-parent-example] for an example configuration.


oss-parent does not yet use Error Prone Support. We should either fix that (preferred) or drop this.

Edit: let's move it to an XXX comment.

README.md

Stephan202 · 2022-08-28T12:10:22Z

README.md

+- `-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
+  code with minimal checks (i.e. without linting, Error Prone checks, etc.)
+- `-Dversion.error-prone=some-version` runs the build using the specified
+  version of Error Prone. This is useful e.g. when testing a locally built Error
+  Prone SNAPSHOT.
+- `-Perror-prone-fork` run the build using Picnic's [Error Prone
+  fork][error-prone-fork-repo], hosted on [Jitpack][error-prone-fork-jitpack].
+  This fork generally contains a few changes on top of the latest Error Prone
+  release.


We should also document -Pself-check. (Right now that profile is compatible only with the fork, as it relies on -XepAllSuggestionsAsWarnings.)

README.md

LICENSE.md

Stephan202 · 2022-08-28T14:36:33Z

README.md

+                        <!-- Error Prone Support's additional bug checkers. -->
+                        <path>
+                            <groupId>tech.picnic.error-prone-support</groupId>
+                            <artifactId>error-prone-contrib</artifactId>
+                            <version>${error-prone-support.version}</version>
+                        </path>


This shows that error-prone-contrib is not a great name. Perhaps we should split this module into more topical smaller modules before open-sourcing 🤔.

Let's discuss this one also in the light of the TestNG migration checks.

error-prone-contrib/README.md

Stephan202 · 2022-08-28T14:37:39Z

error-prone-contrib/README.md

-  sneak in unrelated changes.
- When in doubt about whether a pull request will be accepted, please first
-  file an issue to discuss it.
+See [CONTRIBUTING.md][main-contributing].

 ### Our wishlist


This list should definitely be curated before go-live.

We can move this list to bugcheck-ideas.md and refaster-ideas.md. Let's do in a follow-up.

error-prone-contrib/README.md

rickie

Alternative suggested commit message:

Introduce {CONTRIBUTING,LICENSE,README}.md and Error Prone Support's logo

Thanks for driving this forward @japborst 🚀 !

japborst · 2022-08-31T20:30:52Z

I've added a small bugcheck/refaster usage example. Would appreciate a final look @rickie.

Any remaining feedback @Stephan202?

rickie

Example makes it even nicer, can't wait to see this merged 🚀 !

rickie · 2022-09-02T09:27:26Z

README.md

+[WARNING] COMPILATION WARNING :
+[INFO] -------------------------------------------------------------
+[WARNING] Example.java:[9,34] [tech.picnic.errorprone.refastertemplates.BigDecimalTemplates.BigDecimalZero]
+  null


@Stephan202 this is what we talked about a little while ago, it shows null. We could leave it out here for now or leave it in, fine with both.

Removed it; optimistically assuming this will be solved at some point 😉

rickie · 2022-09-02T09:28:06Z

README.md

+[WARNING] Example.java:[9,34] [tech.picnic.errorprone.refastertemplates.BigDecimalTemplates.BigDecimalZero]
+  null
+  Did you mean 'return BigDecimal.ZERO;'?
+[WARNING] Example.java:[14,35] [IdentityConversion] This method invocation appears redundant; remove it or suppress this warning and add a comment explaining its purpose


@japborst and I talked about it and updated the example. This nicely shows the two SuggestedFixes, which is cool 😄.

svavahb

Very important and impactful review

svavahb · 2022-09-02T11:46:50Z

CONTRIBUTING.md

+on GitHub.
+
+Before doing so, please:
+- Verify that issue is reproducible against the latest version of the project.


Suggested change

- Verify that issue is reproducible against the latest version of the project.

- Verify that the issue is reproducible against the latest version of the project.

^ Still needs to be applied 😄 (Will do.)

japborst · 2022-09-11T09:54:32Z

Rebased and resolved conflicts.

Stephan202 · 2022-09-14T06:44:37Z

CONTRIBUTING.md

+on GitHub.
+
+Before doing so, please:
+- Verify that issue is reproducible against the latest version of the project.


^ Still needs to be applied 😄 (Will do.)

README.md

Stephan202

Partial review. Have a meeting now; more later. I like how this shapes up!

Stephan202 · 2022-09-14T06:54:22Z

error-prone-contrib/README.md

+[checkstyle-external-project-tests]:
+  https://github.com/checkstyle/checkstyle/blob/master/wercker.yml


I know that line-wrapping would have this spread across two lines, but this makes it harder to keep the entries sorted and check whether the keys are "consistent". If/when we introduce Prettier (or similar) to format the file this might be inevitable, but for now let's keep these on a single line. (Like we still do in e.g. CONTRIBUTING.md.)

This was indeed formatted using prettier. Not applying line-length here seems a bit "meten met twee maten" (double standards), but alas.

Yeah, I suspect I'll come around soon enough 🙈

japborst · 2022-09-14T08:59:23Z

Thanks @Stephan202. Agree with the suggestions 👍

Stephan202 · 2022-09-14T15:46:16Z

Rebased and resolved conflict.

Stephan202

Rebased and added two more commits with assorted tweaks. Sorry for the delay; happy that we pulled this off!

Suggested commit message:

Introduce `{CONTRIBUTING,LICENSE,README}.md` and Error Prone Support's logo (#212)

Stephan202 · 2022-09-19T05:39:50Z

error-prone-contrib/README.md

 [modernizer-maven-plugin]: https://github.com/gaul/modernizer-maven-plugin
-[pitest]: https://pitest.org
-[pitest-maven]: https://pitest.org/quickstart/maven
 [sonarcloud]: https://sonarcloud.io


👇 I tried to minify the SVG files using this website, but then the cute bug at the bottom is gone 😅

(But if you know a better way to reduce file size, that'd be nice.)

Note that gzipped, it's already 26kb instead of 110kb.

I optimized them a bit using https://jakearchibald.github.io/svgomg/ (from 100 to ~65kb). When gzipped this is barely an improvement, you go from 26 to 24kb, but alas.

Stephan202 · 2022-09-19T05:45:09Z

@ferdinand-swoboda any other feedback? 😄

@rickie @japborst if you're okay with my latest changes then I think this one is good to go :)

japborst · 2022-09-19T06:44:22Z

Drive by comment: We should put a medium complexity but common before-vs-after use case at the top of the readme so that it's immediately visible what transformations this software enables.

A Bugchecker and Refaster example is now included. Both simple use-cases. An addition of a more complex use-case would be nice to add later (which would be an addition, rather than a replacement, IMHO).

rickie · 2022-09-19T06:48:32Z

Nice improvements! They look good to me :).

japborst · 2022-09-19T06:48:34Z

Changes LGTM. Also verified that all the anchors work.

Let's go 🚀

japborst commented Aug 24, 2022

View reviewed changes

japborst requested review from Stephan202 and rickie August 24, 2022 07:52

ferdinand-swoboda reviewed Aug 24, 2022

View reviewed changes

rickie added the documentation A documentation update label Aug 25, 2022

rickie force-pushed the japborst/readme branch from fe2e885 to ebd7cf0 Compare August 25, 2022 13:39

rickie reviewed Aug 25, 2022

View reviewed changes

Stephan202 reviewed Aug 28, 2022

View reviewed changes

japborst commented Aug 28, 2022

View reviewed changes

error-prone-contrib/README.md Outdated Show resolved Hide resolved

japborst force-pushed the japborst/readme branch from 42910b0 to 51680a9 Compare August 28, 2022 19:27

rickie approved these changes Aug 31, 2022

View reviewed changes

japborst changed the title ~~Set up the project's readme, contributing guidelines, license, and introduce its logo.~~ Set up the project's readme, contributing guidelines, license, and introduce its logo Aug 31, 2022

rickie approved these changes Sep 2, 2022

View reviewed changes

svavahb approved these changes Sep 2, 2022

View reviewed changes

japborst force-pushed the japborst/readme branch from 08a9122 to bbcddb6 Compare September 11, 2022 09:35

Stephan202 reviewed Sep 14, 2022

View reviewed changes

rickie added this to the 0.2.1 milestone Sep 14, 2022

Stephan202 force-pushed the japborst/readme branch from 03190f9 to 603401f Compare September 14, 2022 15:46

japborst added 6 commits September 19, 2022 06:52

Add README.md, GH actions badge and logo

37894b1

Add sections and badges

0a28ea6

Fix urls

5827e39

Use SVG and Picnic red for logo

920ebab

Add licence, logo for dark mode, and contributing docs

86ebb9d

Extent building section in README

67a00f2

rickie and others added 16 commits September 19, 2022 06:52

Update CONTRIBUTING.md

7484045

Rename to LICENSE.md

b3da8f6

Clean up error-prone-contrib/readme.

64f8c66

Link to oss-parent example and format.

986b55e

Clean up links

8b85cf3

Format license

cd0f4f6

Suggestions

f22d327

Sort links

bfceab2

Suggestions

6528450

Small tweaks for readability

56a2644

Improve pom.xml how to show warnings and fail your build

a288549

Fix typos and run format.sh

44dcb12

Add usage example

d5e3b86

Change usage example to one with a suggestedfix

a223371

Remove null

81ece59

Suggestions

2111764

Stephan202 force-pushed the japborst/readme branch from 603401f to a7efb92 Compare September 19, 2022 05:32

Suggestions

1b4e7d7

Stephan202 force-pushed the japborst/readme branch from a7efb92 to 1b4e7d7 Compare September 19, 2022 05:35

Indent list entry code block

80385a2

Stephan202 approved these changes Sep 19, 2022

View reviewed changes

Optimize logo SVG files

d34db4c

japborst changed the title ~~Set up the project's readme, contributing guidelines, license, and introduce its logo~~ Introduce {CONTRIBUTING,LICENSE,README}.md and Error Prone Support's logo Sep 19, 2022

japborst merged commit 84ba394 into master Sep 19, 2022

japborst deleted the japborst/readme branch September 19, 2022 06:50

Stephan202 mentioned this pull request Sep 19, 2022

Add newline at end of logo.svg and logo-dark.svg #247

Merged

	<img alt="Error Prone Support logo'" src="logo.svg" width="50%">
	<img alt="Error Prone Support logo" src="logo.svg" width="50%">

	- Verify that issue is reproducible against the latest version of the project.
	- Verify that the issue is reproducible against the latest version of the project.

		[checkstyle-external-project-tests]:
		https://github.com/checkstyle/checkstyle/blob/master/wercker.yml

Introduce {CONTRIBUTING,LICENSE,README}.md and Error Prone Support's logo #212

Introduce {CONTRIBUTING,LICENSE,README}.md and Error Prone Support's logo #212

Conversation

japborst commented Aug 24, 2022

Choose a reason for hiding this comment

ferdinand-swoboda left a comment • edited Loading

Choose a reason for hiding this comment

japborst commented Aug 24, 2022

rickie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Stephan202 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rickie left a comment

Choose a reason for hiding this comment

japborst commented Aug 31, 2022

rickie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

svavahb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

japborst commented Sep 11, 2022

Choose a reason for hiding this comment

Stephan202 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

japborst commented Sep 14, 2022

Stephan202 commented Sep 14, 2022

Stephan202 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Stephan202 commented Sep 19, 2022

japborst commented Sep 19, 2022

rickie commented Sep 19, 2022

japborst commented Sep 19, 2022 • edited Loading

Introduce `{CONTRIBUTING,LICENSE,README}.md` and Error Prone Support's logo #212

Introduce `{CONTRIBUTING,LICENSE,README}.md` and Error Prone Support's logo #212

ferdinand-swoboda left a comment •

edited

Loading

japborst commented Sep 19, 2022 •

edited

Loading