Skip to content

Record the decisions on surfaces, JDK-specific tests and imports - #230

Merged
abashev merged 9 commits into
21.X.Xfrom
abashev/Architecture-decision-records
Nov 16, 2026
Merged

abashev merged 9 commits into
21.X.Xfrom
abashev/Architecture-decision-records

Conversation

@abashev

@abashev abashev commented Nov 14, 2026

Copy link
Copy Markdown
Collaborator

Four architecture decision records, in docs/decisions/, from the work on #219, #222 and #224. Documentation only; no code changes. Each record is Proposed, and becomes Accepted with this pull request.

  • ADR-001: two entry points, one output for each. Every surface formats a whole file or a part of one. For the same version and input, every surface of an entry gives the same result, and the command line is the reference for whole files. Accepted exceptions for now: the order of fixing imports, Spotless' own step not reflowing long strings, syntax the runtime cannot parse, and a file that does not parse.
  • ADR-002: tests that need a newer JDK, by class and folder. @EnabledForJreRange on the class instead of assumptions inside the tests; case files in test-cases-java21/ and test-cases-java25/, side by side; module imports from JDK 25; value classes gated on the value modifier.
  • ADR-003: imports in IntelliJ IDEA. Reformat never changes imports; Optimize imports does, and the plugin's optimizer is to replace the IDE's through FormatterService.fixImports (IntelliJ plugin: optimize imports with open-java-format, not the IDE's own optimizer #222, after FormatterService.fixImports formats the whole file out of process #221). Includes why palantir-java-format dropped its optimizer in 2024.
  • ADR-004: the order of fixing imports stays as it is until Fix the imports before the layout or after it? #224 decides, with what either order would change.

The changes that follow from them come in pull requests of their own.

Every surface formats a whole file or a part of one, and for the same
version and input every surface of an entry is to give the same
result, with the command line as the reference for whole files. The
record keeps the exceptions accepted for now and the alternatives
turned down (#219).
Such tests skip themselves from inside today, in three ways, and pass
for skipped on JDK 21. They are to carry their condition on the class,
with case files in test-cases-java21/, test-cases-java25/ and so on,
side by side; module imports from JDK 25.
Reformat never changes imports; they change through Optimize imports
only, which the plugin's optimizer is to take over from the IDE's
through FormatterService.fixImports (#222, after #221). The record
keeps why palantir-java-format dropped its optimizer in 2024.
The command line fixes imports after the layout, the Maven plugin and
the Spotless steps before it, and the files differ where a removed
import has a comment. Both stay until #224 decides, with what either
order would change.
@abashev abashev added the documentation Improvements or additions to documentation label Nov 14, 2026
Their tests go by the version that previews them, as the module imports do, rather than by a condition on the value modifier: JDK 28's early-access builds, which CI runs, have it.
Each names the folders its JDK parses, and their ranges do not overlap, so every case runs once on any JDK.
@abashev
abashev merged commit 57bb4da into 21.X.X Nov 16, 2026
17 checks passed
@abashev
abashev deleted the abashev/Architecture-decision-records branch November 16, 2026 20:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant