Apply Palantir Java Format to the entire codebase + enforce on every build

.git-blame-ignore-revs

@@ -0,0 +1,14 @@
+# Commits listed here are skipped by `git blame` so that mechanical, whole-tree
+# reformats do not obscure the author who actually wrote each line.
+#
+# GitHub honors this file automatically in the web blame view. For `git blame`
+# on the command line, opt in once per clone:
+#
+#   git config blame.ignoreRevsFile .git-blame-ignore-revs
+#
+# When adding a new entry, include a one-line comment above the SHA explaining
+# what the commit did and why it should be skipped. Only mechanical reformats
+# belong here -- never use this to hide substantive changes.
+
+# Apply Palantir Java Format to entire codebase (#1761)
+e80374ba8559a0b124e868d906de9fb59482752c

.github/workflows/tests.yml

@@ -71,6 +71,23 @@ jobs:
         with:
           name: test-results-external-apis
           path: build/reports/tests
+  formatCheck:
+    runs-on: ubuntu-latest
+    name: Java Format Check
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0  # full history + tags so palantir/git-version sees the latest release tag
+      - name: Set up java 17
+        uses: actions/setup-java@v3
+        with:
+          java-version: '17'
+          distribution: 'adopt'
+          cache: gradle
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+      - name: Verify formatting
+        run: ./gradlew spotlessCheck
   spotBugs:
     runs-on: ubuntu-latest
     name: SpotBugs

CONTRIBUTING.md

@@ -1,5 +1,38 @@
 # Contributing to HTSJDK
 
+## Code Style
+
+HTSJDK uses [Palantir Java Format](https://github.com/palantir/palantir-java-format)
+(applied via the [Spotless](https://github.com/diffplug/spotless) Gradle plugin)
+to enforce a single, mechanical code style across the codebase. There are no
+formatting knobs to configure -- the formatter is the style guide.
+
+Formatting is applied automatically as part of `compileJava`: every build
+runs `spotlessJavaApply`, which rewrites any unformatted source in place
+before compiling. In normal use you shouldn't need to invoke the formatter
+yourself -- just build, and your code is formatted. If you want to format
+without compiling, run:
+
+```bash
+./gradlew spotlessApply
+```
+
+CI runs `./gradlew spotlessCheck` (verify-only, no mutation) so a PR with
+unformatted code still fails CI -- the local auto-format is a convenience,
+not the enforcement boundary.
+
+### Git blame and the bulk-format commit
+
+The codebase was reformatted in a single mechanical commit. To keep `git blame`
+useful (so you see the author who actually wrote each line, not the reformat
+commit), the repository ships a `.git-blame-ignore-revs` file. GitHub honors
+it automatically in the web UI; for `git blame` on the command line, opt in
+once per clone:
+
+```bash
+git config blame.ignoreRevsFile .git-blame-ignore-revs
+```
+
 ## Building
 
 HTSJDK uses Gradle (via the Gradle wrapper). To build:

build.gradle

@@ -13,6 +13,14 @@ plugins {
     id 'com.gradleup.shadow' version '9.4.1'
     id 'com.github.spotbugs' version "6.4.8"
     id 'com.gradleup.nmcp' version '1.4.4'
+    id 'com.diffplug.spotless' version '8.4.0'
+}
+
+spotless {
+    java {
+        target 'src/**/*.java'
+        palantirJavaFormat()
+    }
 }
 
 repositories {
@@ -135,6 +143,12 @@ defaultTasks 'jar'
 
 tasks.withType(JavaCompile).configureEach {
     options.encoding = 'UTF-8'
+    // Auto-format source as part of every compile. This rewrites unformatted
+    // files in place rather than failing -- contributors don't have to remember
+    // to run `./gradlew spotlessApply` themselves. spotlessJavaApply is fast
+    // (sub-second warm) thanks to Gradle's up-to-date checking. CI separately
+    // runs `spotlessCheck` (verify-only) so unformatted code can't slip past.
+    dependsOn 'spotlessJavaApply'
 }
 
 tasks.withType(Javadoc).configureEach {