|
| 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. |
0 commit comments