Thanks you two, for clearly describing the issue that I'm attempting to
address.
I've updated
https://github.com/jenkinsci/github-branch-source-plugin/pull/392 with the
following changes:
- Source will not be changed during the build unless the user runs a
specific maven goal
- "spotless:check" runs near the end of the lifecycle during the verify
phase during local build. Formatting issues will fail the build, source
remains unchanged.
- "spotless:check" runs near the start of the lifecycle during the
process-sources phase during CI. Formatting issues will fail the build,
source remains unchanged.
- Users may run "mvn spotless:apply" to automatically fix
formatting. This command is easy and short. When "spotless:check" fails
it specifically tells users to run "mvn spotless:apply" to fix formatting.
- I have adjusted the formatting rules to address some of the points
raised during review
- Line comments do not join if wrapped - if you have comments that you
want to not be reformatted, keep them under 120 chars and use line
comments
- Javadoc formatting made a bit more compact
-
https://github.com/jenkinsci/github-branch-source-plugin/pull/392/commits/ea6e28ca69ea24a59584fba3c6190b145dc0925e
- Found a way to force array initializer expansion if that is what is
desired
-
https://github.com/jenkinsci/github-branch-source-plugin/pull/392/commits/43a99508ab640db724e8b673c61855cb57670b82
- Long string arguments getting pushed to the next line? Maybe the
humans involved should split those
up.
https://github.com/jenkinsci/github-branch-source-plugin/pull/392#discussion_r580403349
- I've applied the ".gitattributes" suggested by Joseph. The build
now passes on Windows.
- I have also not addressed a number of other places where people have
said the formatting looks "worse". These cases are generally
debatable/personal-preference. In some of these cases I agree with the
assessment but I don't see it as a blocker. If anyone disagrees with that
evaluation, feel free to say so and explain why.
-
https://github.com/jenkinsci/github-branch-source-plugin/pull/392#discussion_r580104724
-
see
https://github.com/bitwiseman/github-branch-source-plugin/pull/new/task/formatting-test-cleanup
-
https://github.com/jenkinsci/github-branch-source-plugin/pull/392#discussion_r580105388
- same as previous
-
https://github.com/jenkinsci/github-branch-source-plugin/pull/392#discussion_r580402264
-
https://github.com/jenkinsci/github-branch-source-plugin/pull/392#discussion_r580510020
-
https://github.com/jenkinsci/github-branch-source-plugin/pull/392#discussion_r580513803
Note: I am using the eclipse formatter rather than to google formatter in
an attempt to reduce the severity of the diff wall and disruption to folks
familiar with the current code style. There are still significant
differences, but they are far less than switching to google formatting.
However, that is still an option. You can see what it would look like
here:
https://github.com/bitwiseman/github-branch-source-plugin/pull/new/task/formatting-google
On Wednesday, February 24, 2021 at 4:10:26 PM UTC-8 [email protected]
wrote:
> On Wed, Feb 24, 2021 at 3:32 AM [email protected] <[email protected]>
> wrote:
> >
> > What I feel is also missing here is what issue is this attempting to
> solve.
> > It is proposing a solution - but what is the exact problem maintainers
> are
> > seeing; perhaps there are better ways to solve that?
>
> The problem, to me, is twofold:
>
> 1. Lack of convenient formatting tools means one has to consciously think
> about formatting when writing new code or changing existing code. This
> slows down the development process.
> 2. Lack of a consistently enforced formatting style throughout a
> repository leads to PRs that change both logic and formatting style.
> This slows down the review process.
>
> Over the years I have led a number of efforts to reformat legacy codebases
> and enforce the new formatting style consistently at build time, both in
> Java (using Google Java Format) and Python (using Black). My experience is
> that while the "diff wall" described by Mark does initially lead to some
> frustration, the long term benefits of a consistently enforced formatting
> style eventually outweigh the initial costs. In my experience, the key
> takeaways are:
>
> 1. Choose a formatting tool that exposes extremely few (if any)
> configuration options and that formats the majority of code at high
> quality.
> 2. Provide developers with a single command (not executed by default) to
> automatically format their code prior to committing it (ideally also
> with IDE integration).
> 3. Enforce that the entire repository is consistently formatted during the
> build system's "verify" phase (Maven) or "check" task (Gradle), but do
> not change any existing code as part of this process.
>
> This solves the originally mentioned problem as follows:
>
> 1. A formatting tool that is integrated with the build system means that
> one no longer has to consciously think about formatting when writing
> new code or changing existing code. This speeds up the development
> process.
> 2. A consistently enforced formatting style throughout a repository
> eliminates PRs that change both logic and formatting style. There is
> only one formatting style, and that is the style imposed by the
> formatting tool during the build (otherwise the build is unstable).
> This speeds up the review process.
>
> Some practical notes:
>
> 1. The Eclipse JDT formatter is very customizable, but customizability is
> a non-goal when trying to enforce a consistent formatting style across
> an entire repository.
> 2. Google Java Format [1] and Black [2] are intentionally not customizable
> and format the majority of code at high quality.
> 3. One exception to the above with Google Java Format is that it supports
> an "AOSP mode" to switch from 2-space indentation to 4-space
> indentation. One might be tempted to use this mode when formatting a
> legacy codebase that already uses 4-space indentation; however, the
> result is often unreadable lambda expressions [3], and the maintainers
> do not appear to be willing to address this. I highly recommend
> avoiding this "AOSP mode" and using the default (2-space indentation)
> mode when formatting a codebase with Google Java Format.
>
> [1] https://github.com/google/google-java-format/wiki/FAQ
> [2] https://github.com/psf/black#the-black-code-style
> [3] https://github.com/google/google-java-format/issues/19
>
--
You received this message because you are subscribed to the Google Groups
"Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/jenkinsci-dev/64981cbc-5292-46ab-96b3-6c351978487cn%40googlegroups.com.
