add spotless #538

jetersen · 2022-04-11T19:39:26Z

Implement spotless with sane defaults. I don't think we need to go down the rabbit hole of configuration.
I added an example for <sort.nrOfIndentSpace>2</sort.nrOfIndentSpace>

I would like to remove it simply keep sane defaults and than if someone dislike it they can either override the configuration or use spotless.check.skip to skip.

At the moment this opt-out via <spotless.check.skip>true</spotless.check.skip>

If there is any desire we can also make it opt-in by setting it to default <spotless.check.skip>false/spotless.check.skip>

Not sure who should be pinged to properly review this.

@basil

Make sure you are opening from a topic/feature/bugfix branch (right side) and not your main branch!
Ensure that the pull request title represents the desired changelog entry
Please describe what you did
Link to relevant issues in GitHub or Jira
Link to relevant pull requests, esp. upstream and downstream changes
Ensure you have provided tests - that demonstrates feature works or fixes the issue

jetersen · 2022-04-11T19:42:41Z

pom.xml

+        <configuration>
+          <java>
+            <endWithNewline />
+            <importOrder />


@timja this import order might mess with how we have configured in checkstyle, but we could simply adapt to the order so that static was on top.

https://github.com/jenkinsci/configuration-as-code-plugin/blob/1bed6f13340e0d7bdd2c578d9ead394eedd39555/.mvn/checkstyle.xml#L12-L19

heh low level of caring what the actual order is as long as it's defined and enforced in code :).

happy to change when we update the parent pom

daniel-beck · 2022-04-11T19:46:10Z

Implement spotless with sane defaults. I don't think we need to go down the rabbit hole of configuration.
I added an example for <sort.nrOfIndentSpace>2</sort.nrOfIndentSpace>

I was so confused by this; to clarify: This is indentation of the pom, correct?

jetersen · 2022-04-11T19:52:42Z

I was so confused by this; to clarify: This is indentation of the pom, correct?

https://github.com/diffplug/spotless/blob/main/plugin-maven/README.md#sortpom
Yes, that is indentation of the POM.

timja · 2022-04-11T19:55:38Z

README.md

@@ -54,6 +54,18 @@ If you had a `jar:test-jar` execution, delete it and add to `properties`:
 <no-test-jar>false</no-test-jar>
 ```

+To fix spotless validation errors:


may want to mention this: https://github.com/jenkinsci/github-branch-source-plugin/blob/master/.git-blame-ignore-revs

(may be more appropriate in release notes)

Sure, we can add it in the readme and the release notes.

basil · 2022-04-11T19:59:37Z

This looks really great. Thanks for starting this effort. I will try this on a few of the plugins I maintain and see how it works. I want to explore the various settings we expose to users. In order to avoid disruption, I think any new functionality should be off by default, unless the vast majority of existing plugin POMs already comply. And as far as opting in to new functionality, I think there are two types of users:

Those who care at least a little bit about the Git history, and would be happy to opt in to something like reordering dependencies or removing unused imports in Java files, but would not want anything more drastic.
Those who don't care about the Git history at all and are OK with a "Git wall", including re-indenting pom.xml files and e.g. reformatting all Java files with Google Java Format.

Whatever interface we come up with should support both types of users, I think. For example, core has accepted import management and POM ordering from Spotless, but I doubt the core maintainers would be receptive to formatting every Java source file with Google Java Format. In contrast, Liam Newman did reformat one of his plugins with Google Java Format, and he was OK with the "diff wall". So we need to keep both types of users in mind in order for such a change to be adopted without complaints.

timja · 2022-04-11T20:02:52Z

Those who don't care about the Git history at all and are OK with a "Git wall", including re-indenting pom.xml files and e.g. reformatting all Java files with Google Java Format.

FWIW https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view

git blame --ignore-revs-file .git-blame-ignore-revs

basil · 2022-04-11T20:09:05Z

I know, and I also use git blame -w by default. I am not one of the people who care about a "Git wall." But I know from experience that some others care strongly, and I expect there would be serious resistance to such a change from those people without a way of opting out.

daniel-beck · 2022-04-11T20:20:16Z

pom.xml

@@ -116,6 +116,8 @@
    <scmTag>HEAD</scmTag>
    <!-- Where to put temporary files during test runs. -->
    <surefireTempDir>${project.build.directory}/tmp</surefireTempDir>
+    <spotless.version>2.22.1</spotless.version>
+    <sort.nrOfIndentSpace>2</sort.nrOfIndentSpace>


Suggested change

<sort.nrOfIndentSpace>2</sort.nrOfIndentSpace>

<sortPom.nrOfIndentSpace>2</sort.nrOfIndentSpace>

Maybe? (+ downstream changes)

Or even

Suggested change

<sort.nrOfIndentSpace>2</sort.nrOfIndentSpace>

<spotless.sortPom.nrOfIndentSpace>2</sort.nrOfIndentSpace>

to make it really obvious what this is related to.

I am fine with

Suggested change

<sort.nrOfIndentSpace>2</sort.nrOfIndentSpace>

<spotless.sortPom.nrOfIndentSpace>2</spotless.sortPom.nrOfIndentSpace>

jetersen · 2022-04-11T20:24:26Z

Regarding git blame, I suggest creating a PR afterwards to avoid commit sha changing on us in this PR if we use squash or rebase.

But definitely a good suggestion :)

jetersen · 2022-04-11T20:30:57Z

@basil my only concern if we open up the property list to fully configure each little aspect of spotless we will have 20-30 new properties.

My suggestion is to only have <spotless.check.skip>true</spotless.check.skip> to opt out and the rest is default.
As I mentioned I would prefer to remove nrOfIndentSpace property. Defaults are there for a reason. No bickering, please 😅

jetersen · 2022-04-11T20:41:53Z

Apparently dependency order matters when it comes to commons-logging: see #132

@jtnord do you have any suggestion on your TODO, how should this be fixed so that order did not matter?

    <dependency>
      <!-- to avoid https://www.slf4j.org/codes.html#release warning -->
      <!-- TODO this would be better as a managed version of [0] -->
      <groupId>commons-logging</groupId>
      <artifactId>commons-logging</artifactId>
      <scope>provided</scope>
    </dependency>

basil · 2022-04-11T20:46:38Z

Yeah, I definitely don't think that the interface between the plugin parent POM and plugin POMs should expose every internal Spotless tunable that exists. That would be impossible to support in the long term as Spotless tunables evolve upstream. But I am not sure that an "all or nothing" approach of all Spotless checks or none of them is ideal either. For one thing, the existing "all" implementation in this PR doesn't satisfy me, as it doesn't run Google Java Format on every Java source file. :-) But to give another perspective, I think the percentage of people that are excited enough by this sort of thing to enable the "all" mode are relatively few, and I think the vast majority of people would stay in the "none" mode to avoid having to do any work. I think we might be able to curate a "middle ground" of less disruptive changes that might appeal to more people with a minimum amount of effort. If that "middle ground" is undisruptive enough, we could even consider enabling it by default.

jetersen · 2022-04-11T20:52:05Z

on every Java source file

I take it you mean test files? Yes, we should 😄

"middle ground"

I guess getting consensus for that would change over time, we should be prepared for changes to the settings than.
Also hard to define initially. I don't feel too strongly about any specific settings, all I suggest we provide sane defaults.
Without too much property overload.

basil · 2022-04-11T20:55:06Z

I'm saying that if I wanted to apply Spotless to my plugins, by "opting in" to some mode (whatever we decide to call it or name the property), I'd want it to run SortPom with maximum awesomeness (e.g., enforcing 2-space indentation, dependency sorting, all the good stuff) and Google Java Format with maximum awesomeness (e.g., full reformatting of every Java file in src/main and src/test with 2-space indentation and all other Google Java Format rules). I think the current PR stops short of that, which would hinder me from adopting it.

basil · 2022-04-11T21:06:03Z

The way I have been thinking about this in my mind is that we could define some "profiles" for formatting: e.g. "none" (no Spotless at all), "low" (some changes, like eliminating unused imports in Java code and conservative changes to pom.xml, but not going all out), and "high" (full-on dependency sorting and enforcing of 2-space indentation and Google Java Format rules). The default could be "low", as long as the changes are conservative enough to not bother too many people. People who are still bothered (there will always be a few) can opt out to "none", while source code formatting enthusiasts like myself can opt in to "high" to get very strict enforcement (at the cost of some extra effort).

jetersen · 2022-04-11T21:17:47Z

Profiles might be a good suggestion 🤔

basil · 2022-04-11T21:28:15Z

I think implementation wise it would be pretty easy, too: we could define a Jenkins-specific property to determine which profile to use, and then define several different Maven profiles with the different spotless settings, with the activation for each Maven profile being based on the value of the Jenkins-specific property.

basil · 2022-04-11T21:39:05Z

Oh right I keep forgetting that Maven profile activation works with system properties and not with Maven properties. But the gist of my idea is the same. You could instead enable or disable the Maven profiles for the different "Jenkins formatting profiles" in .mvn/maven.config.

jtnord · 2022-04-14T15:41:11Z

Apparently dependency order matters when it comes to commons-logging: see #132

Order matters period. it is not just about commons-logging but this is how maven and dependencies work.

if you have A depends on B1 and C depends on B2

if you declare your dependencies as A first then C you will get B1, if you decalare the dependenci on C first you get B1.

Then you have the enforcer upper-bounds errors which are a way to try and detect / prevent this.

Also you have the classpath order which is dependant (possibly) on the dependency order.

TL;DR enforcing a sort order of dependencies is incorrect.

@jtnord do you have any suggestion on your TODO, how should this be fixed so that order did not matter?

    <dependency>
      <!-- to avoid https://www.slf4j.org/codes.html#release warning -->
      <!-- TODO this would be better as a managed version of [0] -->
      <groupId>commons-logging</groupId>
      <artifactId>commons-logging</artifactId>
      <scope>provided</scope>
    </dependency>

could possibly be dependencyManage as a version number such as commons-logging-dependency-should-be-excluded-jenkins-provides-jcl-over-slf4j (or added to the banned dependency list in the enforcer plugin)?

jtnord · 2022-04-14T15:44:03Z

Oh right I keep forgetting that Maven profile activation works with system properties and not with Maven properties. But the gist of my idea is the same. You could instead enable or disable the Maven profiles for the different "Jenkins formatting profiles" in .mvn/maven.config.

IIRC this approach does not work for multi-module projects or aggregators, where you require different config per module.

jtnord · 2022-04-14T15:48:46Z

pom.xml

+            <endWithNewline />
+            <importOrder />
+            <indent>
+              <spaces>true</spaces>


tabs ;-p

Suggested change

<spaces>true</spaces>

<spaces>false</spaces>

jtnord · 2022-04-14T15:50:00Z

pom.xml

+          </java>
+          <pom>
+            <sortPom>
+              <encoding>${project.build.sourceEncoding}</encoding>


POMs are XML and will be UTF-8 by default not always the sourceEncoding?
if the spotless pom parser can not handle XML correctly and detect the encoding - please raise a bug against it.

jtnord · 2022-04-14T15:51:43Z

pom.xml

+          <pom>
+            <sortPom>
+              <encoding>${project.build.sourceEncoding}</encoding>
+              <lineSeparator>\n</lineSeparator>


this would probably a lot of windows setups where the line ending will get converted.
(not mine as I use as-is - but possibly many others).

also diffplug/spotless#1559

jtnord · 2022-04-14T15:52:51Z

pom.xml

+          </pom>
+        </configuration>
+        <executions>
+          <execution>


should have an id so it can be changed / overridden correctly in child projects?

jtnord · 2022-04-14T15:54:59Z

pom.xml

+        </configuration>
+        <executions>
+          <execution>
+            <!-- Runs in verify phase by default -->


TBH - this is one of the worst things. you run the tests everything passes locallay then 20+ minutes later CI says no just because of some trailing space...

Should be run much earlier in the lifecycle IMO (e.g. validate) and be disabled with the quick-build profile (which it is)

jtnord · 2022-04-14T16:02:46Z

given this is a breaking change (it will cause builds to fail, and I guess many of them are not formatted as per the rules) I think it should be opt-in (then there is the question of how this impacts plugins that currently have it enabled. (with DB most people probably ignore any "upgrade notes" unless a build fails, and in the case we disable spotless unless you then set a flag, it could cause spotless to be silently disabled).

I am not against enabling spotless, but if different plugin authors all require different settings, is having the configuration in here the best solution?

basil · 2023-04-09T17:15:19Z

Closing in favor of #733.

jetersen added 2 commits April 11, 2022 21:30

add spotless

43f4343

spotless apply

260887f

jetersen commented Apr 11, 2022

View reviewed changes

timja reviewed Apr 11, 2022

View reviewed changes

daniel-beck reviewed Apr 11, 2022

View reviewed changes

jtnord reviewed Apr 14, 2022

View reviewed changes

jtnord requested a review from Vlatombe April 14, 2022 15:55

basil mentioned this pull request Apr 1, 2023

Enable Spotless for automatic formatting #733

Merged

basil closed this Apr 9, 2023

jetersen deleted the feat/spotless branch April 11, 2023 09:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add spotless #538

add spotless #538

jetersen commented Apr 11, 2022 •

edited

Loading

jetersen Apr 11, 2022

timja Apr 11, 2022

daniel-beck commented Apr 11, 2022

jetersen commented Apr 11, 2022

timja Apr 11, 2022

jetersen Apr 11, 2022

basil commented Apr 11, 2022

timja commented Apr 11, 2022

basil commented Apr 11, 2022

daniel-beck Apr 11, 2022

jetersen Apr 11, 2022

jetersen commented Apr 11, 2022

jetersen commented Apr 11, 2022 •

edited

Loading

jetersen commented Apr 11, 2022 •

edited

Loading

basil commented Apr 11, 2022

jetersen commented Apr 11, 2022

basil commented Apr 11, 2022 •

edited

Loading

basil commented Apr 11, 2022

jetersen commented Apr 11, 2022

basil commented Apr 11, 2022

basil commented Apr 11, 2022

jtnord commented Apr 14, 2022

jtnord commented Apr 14, 2022

jtnord Apr 14, 2022

jtnord Apr 14, 2022 •

edited

Loading

jtnord Apr 14, 2022

jtnord Mar 9, 2023

jtnord Apr 14, 2022

jtnord Apr 14, 2022

jtnord commented Apr 14, 2022

basil commented Apr 9, 2023

	<sort.nrOfIndentSpace>2</sort.nrOfIndentSpace>
	<sortPom.nrOfIndentSpace>2</sort.nrOfIndentSpace>

	<sort.nrOfIndentSpace>2</sort.nrOfIndentSpace>
	<spotless.sortPom.nrOfIndentSpace>2</sort.nrOfIndentSpace>

	<sort.nrOfIndentSpace>2</sort.nrOfIndentSpace>
	<spotless.sortPom.nrOfIndentSpace>2</spotless.sortPom.nrOfIndentSpace>

add spotless #538

add spotless #538

Conversation

jetersen commented Apr 11, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daniel-beck commented Apr 11, 2022

jetersen commented Apr 11, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

basil commented Apr 11, 2022

timja commented Apr 11, 2022

basil commented Apr 11, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jetersen commented Apr 11, 2022

jetersen commented Apr 11, 2022 • edited Loading

jetersen commented Apr 11, 2022 • edited Loading

basil commented Apr 11, 2022

jetersen commented Apr 11, 2022

basil commented Apr 11, 2022 • edited Loading

basil commented Apr 11, 2022

jetersen commented Apr 11, 2022

basil commented Apr 11, 2022

basil commented Apr 11, 2022

jtnord commented Apr 14, 2022

jtnord commented Apr 14, 2022

Choose a reason for hiding this comment

jtnord Apr 14, 2022 • edited Loading

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

jtnord commented Apr 14, 2022

basil commented Apr 9, 2023

jetersen commented Apr 11, 2022 •

edited

Loading

jetersen commented Apr 11, 2022 •

edited

Loading

jetersen commented Apr 11, 2022 •

edited

Loading

basil commented Apr 11, 2022 •

edited

Loading

jtnord Apr 14, 2022 •

edited

Loading