Skip to content

Commit 967e28d

Browse files
committed
Write the home page and bring the manifesto over
The home page leads with the tagline and backs it with three reasons a formatter is the first check for machine-written code, an example against google-java-format, and a quick start for Gradle, the command line and GitHub Actions. Gradle shows the Groovy DSL first and Kotlin second. Spotless is not mentioned anywhere. The manifesto moves here from the formatter repository word for word, with one link added so that "the repository" names the formatter. Section tabs are on because the home page hides its sidebars. The avatar files and the notes about the mark move into icon/; the mark and the favicon already live where the site reads them.
1 parent 1d94898 commit 967e28d

7 files changed

Lines changed: 309 additions & 5 deletions

File tree

‎docs/index.md‎

Lines changed: 144 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,146 @@
1-
# open-java-format
1+
---
2+
title: The first guardrail for AI-written Java
3+
hide:
4+
- navigation
5+
- toc
6+
---
27

3-
A modern, lambda-friendly, 120-character Java formatter, built in the open.
8+
# The first guardrail for AI-written Java
49

5-
This site is being set up. Until the documentation lands here, everything lives in the
6-
[project README](https://github.com/openjavaformat/open-java-format#readme).
10+
**open-java-format** is a deterministic formatter for Java. There is one style and nothing to tune,
11+
so every file comes out the same way, whether a person or a model wrote it.
12+
13+
[Quick start](#quick-start){ .md-button .md-button--primary }
14+
[View on GitHub](https://github.com/openjavaformat/open-java-format){ .md-button }
15+
16+
## Why formatting comes first
17+
18+
<div class="grid cards" markdown>
19+
20+
- :lucide-equal:{ .lg .middle } __One style, nothing to tune__
21+
22+
---
23+
24+
The output depends only on the input. There is no line-length setting, no indentation setting
25+
and no per-team dialect for an agent to get wrong. The IDE, the command line and CI all produce
26+
the same bytes.
27+
28+
- :lucide-git-pull-request-arrow:{ .lg .middle } __Diffs a reviewer can read__
29+
30+
---
31+
32+
Models write a lot of code quickly. When all of it is laid out the same way, a diff shows what
33+
changed in the logic, not how a particular model likes to wrap its lines.
34+
35+
- :lucide-zap:{ .lg .middle } __Fast enough to run after every edit__
36+
37+
---
38+
39+
The formatter ships as a native binary with no JVM to start, so it fits into an agent hook, a
40+
pre-commit hook or a CI step. It also comes as a Gradle plugin and as plugins for IntelliJ IDEA
41+
and Eclipse.
42+
43+
</div>
44+
45+
A formatter does not find bugs. It is the first check in the chain, ahead of the compiler, static
46+
analysis, tests and review, and it is the cheapest one to automate.
47+
48+
## What the output looks like
49+
50+
Lines are up to 120 characters wide. A lambda stays on the line where it starts, and a long call
51+
chain breaks into one call per line.
52+
53+
=== "open-java-format"
54+
55+
``` java
56+
private static void configureResolvedVersionsWithVersionMapping(Project project) {
57+
project.getPluginManager().withPlugin("maven-publish", plugin -> {
58+
project.getExtensions()
59+
.getByType(PublishingExtension.class)
60+
.getPublications()
61+
.withType(MavenPublication.class)
62+
.configureEach(publication -> publication.versionMapping(mapping -> {
63+
mapping.allVariants(VariantVersionMappingStrategy::fromResolutionResult);
64+
}));
65+
});
66+
}
67+
```
68+
69+
=== "google-java-format"
70+
71+
``` java
72+
private static void configureResolvedVersionsWithVersionMapping(Project project) {
73+
project.getPluginManager()
74+
.withPlugin(
75+
"maven-publish",
76+
plugin -> {
77+
project.getExtensions()
78+
.getByType(PublishingExtension.class)
79+
.getPublications()
80+
.withType(MavenPublication.class)
81+
.configureEach(
82+
publication ->
83+
publication.versionMapping(
84+
mapping -> {
85+
mapping.allVariants(
86+
VariantVersionMappingStrategy
87+
::fromResolutionResult);
88+
}));
89+
});
90+
}
91+
```
92+
93+
## Quick start
94+
95+
=== "Gradle"
96+
97+
=== "Groovy"
98+
99+
``` groovy title="build.gradle"
100+
plugins {
101+
id 'dev.openjavaformat.java-format' version '2.98.0.1'
102+
}
103+
```
104+
105+
=== "Kotlin"
106+
107+
``` kotlin title="build.gradle.kts"
108+
plugins {
109+
id("dev.openjavaformat.java-format") version "2.98.0.1"
110+
}
111+
```
112+
113+
The plugin configures IntelliJ IDEA to use the formatter and adds the `formatDiff` task, which
114+
formats only the lines you changed in git.
115+
116+
=== "Command line"
117+
118+
Every [release](https://github.com/openjavaformat/open-java-format/releases/latest) carries
119+
native binaries for Linux and macOS, and a runnable jar for Java 21 or later.
120+
121+
``` sh title="Format files in place"
122+
open-java-format --ojf --replace src/main/java/com/example/Hello.java
123+
```
124+
125+
``` sh title="Fail when anything is not formatted"
126+
open-java-format --ojf --dry-run --set-exit-if-changed $(git ls-files '*.java')
127+
```
128+
129+
=== "GitHub Actions"
130+
131+
``` yaml title=".github/workflows/format.yml"
132+
- uses: actions/checkout@v7
133+
134+
- uses: openjavaformat/open-java-format-action@v1
135+
with:
136+
version: '2.98.0.1'
137+
```
138+
139+
The [action](https://github.com/openjavaformat/open-java-format-action) downloads the native
140+
binary and fails the job when a changed file is not formatted. It needs no Java on the runner.
141+
142+
## A drop-in for palantir-java-format
143+
144+
For the whole 2.x line the output is byte-for-byte the same as the palantir-java-format release
145+
with the same version number, and the Java packages are unchanged. Migrating means changing the
146+
coordinates and nothing else.

‎docs/manifesto.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# The open-java-format Manifesto
2+
3+
## Preamble
4+
5+
Every language that solved code formatting solved it the same way: one obvious tool, owned by
6+
nobody in particular, that everyone runs and nobody argues about. Go has `gofmt`. Rust has
7+
`rustfmt`. Python has `black` and now `ruff format`. JavaScript has `prettier`. Zig ships
8+
`zig fmt` in the compiler.
9+
10+
Java does not have this. Java has two good formatters, and both of them belong to a corporation:
11+
[google-java-format](https://github.com/google/google-java-format) and
12+
[palantir-java-format](https://github.com/palantir/palantir-java-format).
13+
14+
This is not an accusation. Google and Palantir both did excellent engineering and both released it
15+
under Apache 2.0, which is why this project can exist at all. We are standing on their work and we
16+
say so on every page.
17+
18+
It is a structural observation. A tool that we ask every Java project in the world to run in its
19+
build should not depend on one company's release engineer, one company's private CI credentials,
20+
one company's product roadmap, or one company's public reputation. Those are four separate single
21+
points of failure, and today the Java ecosystem has no formatter that is free of all four.
22+
23+
**open-java-format exists to fix the structure, not the code.** The formatting algorithm is good.
24+
The way it reaches you is not.
25+
26+
## Principles
27+
28+
### 1. Formatting is shared infrastructure
29+
30+
A formatter is not a product. It is a fixed point that a community agrees on so it can stop
31+
discussing whitespace. Infrastructure that everyone depends on should be governed like
32+
infrastructure: in public, by more than one party, with the rules written down.
33+
34+
### 2. The name must be neutral
35+
36+
Nobody should have to justify a dependency's brand to a security reviewer, a procurement team, or
37+
a colleague who has never heard of the company. A whitespace tool should not start a political
38+
conversation, and an unfamiliar corporate name in a build file is friction even for people with no
39+
opinion at all.
40+
41+
There is also a legal reason, and it applies to any fork: Apache 2.0 §6 grants patent and copyright
42+
rights but explicitly **no trademark rights**. A fork may use the code; it may not use the name.
43+
The rename is not optional, so we treat it as an opportunity rather than a cost.
44+
45+
### 3. Every artifact is built in public
46+
47+
No binary ships that you cannot trace back to a public commit, a public workflow run, and a
48+
published provenance attestation. Every jar, every plugin, every native image, on every platform,
49+
built by a workflow you can read and re-run.
50+
51+
This matters most for the native images. A compiled binary produced on infrastructure that nobody
52+
outside the company can inspect is a trust assertion, not a supply chain. "Trust us" is exactly the
53+
thing we are trying to remove.
54+
55+
### 4. Output stability is a contract
56+
57+
This formatter's output lives in millions of lines of other people's repositories. A change in
58+
output is an API break, and it lands as a diff on someone's Monday morning. Style changes ship only
59+
in versioned, documented, deliberately-chosen increments — never as a side effect of a bug fix,
60+
never silently, never in a patch release.
61+
62+
### 5. Drop-in first, opinions later
63+
64+
Migration must be one line in one file. Byte-identical output to the version you were already
65+
using, verified by a differential test over a large public corpus, not by assertion. We earn the
66+
right to have opinions about style only after we have proven we can be boring.
67+
68+
### 6. Every contribution gets an answer
69+
70+
Merge, change request, or a stated reason for "no" — within a published window. "No" is a perfectly
71+
good answer and maintainers are allowed to give it. Silence is not an answer, and a PR that sits
72+
for a year because it is not on some company's quarterly roadmap is the failure mode we are
73+
forking away from.
74+
75+
### 7. Upstream is family, not competition
76+
77+
We are a fork, not a rival. Fixes we make flow back to palantir-java-format, and to
78+
google-java-format where they apply. We track upstream for as long as tracking upstream serves
79+
users. We keep the copyright headers, the attribution, and the credit — permanently, and not only
80+
because the licence requires it.
81+
82+
### 8. No single point of failure, including us
83+
84+
The whole argument of this document is that one owner is one owner too few. That applies to the
85+
current maintainers of this fork. Ownership here is temporary by design: multiple maintainers with
86+
release credentials, a written succession plan, and the explicit intent to hand the project to a
87+
neutral foundation once it has earned the right to ask.
88+
89+
## What this is not
90+
91+
- **Not a licence dispute.** Apache 2.0 in, Apache 2.0 out. Nothing was taken away from anyone.
92+
Unlike OpenTofu, Valkey, OpenSearch or OpenBao, we have no relicensing to react to and nothing to
93+
demand. This manifesto is a set of standing promises, not an ultimatum.
94+
- **Not a hostile fork.** We would be delighted to become redundant. If the upstream projects adopt
95+
open builds, open governance and a neutral home, that is a better outcome than this repository
96+
succeeding.
97+
- **Not a rewrite.** We are not going to redesign the formatting algorithm to prove we can.
98+
- **Not a rebrand-and-abandon.** A fork that ships one release and dies has made the ecosystem
99+
worse, not better. If we cannot sustain releases, we will say so in public and hand the keys over.
100+
101+
## Endorsing
102+
103+
If you want this to exist, say so — star [the repository](https://github.com/openjavaformat/open-java-format), open an issue introducing yourself and
104+
your project, or add your name or organisation to `SUPPORTERS.md`. Adoption is the only argument
105+
that matters, and a fork with users is a fork with a future.

‎icon/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Icon
2+
3+
A broken method chain: one long line, then a group of shorter ones sharing a left edge, with a
4+
column guide down the right. It is the formatter's own output shape — the thing that distinguishes
5+
it is deciding *where* to break and what to line up, not laying everything out uniformly.
6+
7+
| File | Use |
8+
|---|---|
9+
| `../overrides/.icons/ojf/logo.svg` | The mark, in the place where the site inlines it as its logo. Inherits `currentColor`, so one file covers light, dark and monochrome. |
10+
| `../docs/assets/favicon.svg` | Same geometry, guide at full strength. Below ~24px contrast is what keeps the guide visible, not shape. |
11+
| `avatar.svg` | The mark on a white rounded square, for the GitHub organisation and marketplace tiles. |
12+
| `avatar-512.png`, `avatar-128.png` | Rasterised from `avatar.svg`; GitHub organisation avatars must be raster. |
13+
14+
Regenerate the PNGs after editing the SVG:
15+
16+
```bash
17+
rsvg-convert -w 512 -h 512 icon/avatar.svg -o icon/avatar-512.png
18+
rsvg-convert -w 128 -h 128 icon/avatar.svg -o icon/avatar-128.png
19+
```
20+
21+
## What not to break
22+
23+
The mark has seven elements, which is the ceiling for 16px. Anything added has to displace
24+
something else.
25+
26+
- **The shared right edge does the work.** The first and third bars end on the same x. That
27+
implied vertical is what carries "there is a boundary" at sizes where the dashes disappear, and
28+
it costs nothing because no thin element draws it. Changing either bar's width breaks the idea
29+
silently — the icon will still look fine at 64px and mean nothing at 16px.
30+
- **The guide's rhythm must not match the bars'.** Three dashes against four bars is deliberate:
31+
mismatched rhythms read as two layers, so the boundary belongs to the format rather than to any
32+
one line. Align them and the dashes turn into decoration stuck on the bar ends.
33+
- **Check every edit at 16px first.** Every version of this mark looked fine large. The small size
34+
is the only one that rejects anything.
35+
36+
The two colours in `avatar.svg` are the only brand decision baked in here, and they are a
37+
placeholder. The white ground means that on GitHub's light theme the tile itself disappears and
38+
only the mark reads; an off-white ground keeps the tile visible if that is preferred.

‎icon/avatar-128.png‎

2.6 KB
Loading

‎icon/avatar-512.png‎

11.7 KB
Loading

‎icon/avatar.svg‎

Lines changed: 20 additions & 0 deletions
Loading

‎zensical.toml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ edit_uri = "https://github.com/openjavaformat/docs/edit/main/docs/"
1616

1717
nav = [
1818
{ "Home" = "index.md" },
19+
{ "Manifesto" = "manifesto.md" },
1920
]
2021

2122
# extra_css = ["stylesheets/extra.css"]
@@ -49,7 +50,7 @@ features = [
4950
"navigation.path",
5051
# "navigation.prune",
5152
"navigation.sections",
52-
# "navigation.tabs",
53+
"navigation.tabs",
5354
# "navigation.tabs.sticky",
5455
"navigation.top",
5556
"navigation.tracking",

0 commit comments

Comments
 (0)