awesome-java: a generated list whose freshness marks only last as long as its build

The first line of README.md says not to edit README.md

The file opens with a comment that answers the question every contributor asks first:

<!-- Generated from README_SOURCE.md by .github/scripts/GenerateReadme.java. Do not edit README.md directly. -->

So the list has two forms. `README_SOURCE.md` is where an entry belongs, and `README.md` is what a generator under `.github/scripts/` produces from it. The repository root holds the source file, the generated file, `CONTRIBUTING.md`, a `LICENSE`, a separate `LICENSE-CODE`, an `.editorconfig`, `.gitattributes` and a `mise.toml` for the toolchain. Two practical consequences. A pull request that edits `README.md` is editing a build artefact and its work disappears at the next run, so the contribution path is through `README_SOURCE.md`. And because the generator is written in Java, regenerating the list locally needs a JVM, which is an unusual prerequisite for editing a markdown document and the reason the toolchain is pinned in `mise.toml`. The two licence files are worth separating in your head as well: the list's own text is CC-BY-SA-4.0, while the generator code carries its own licence, so reusing the prose and reusing the script are different permissions.

839 projects in 81 categories is a map, not a ranking

The header states the shape of the collection: 839 projects, 81 categories and 85 resources. The categories run alphabetically from API Compatibility through Architecture, Artificial Intelligence, Bean Mapping, Bot Development, Build, Bytecode Manipulation and Caching, all the way to Version Managers, Web Crawling, Web Frameworks and Workflow Orchestration Engines. Each one is a collapsible section with a project count in the summary, a one line description of what belongs there, and then the entries. Below the projects sit the resources, in seven groups: Related Awesome Lists, Communities, Guides and References, Influential Books, Podcasts and Screencasts, People, and Websites. What this structure gives you is a decision procedure. A category with three projects is a shortlist someone else already made, a category with dozens is a survey you have to run yourself, and the resources section is the part that ages slowest because books and communities do not churn. What it does not give you is a top ten, so any question of that shape has to be answered by choosing a category first.

The activity dot is a build-time fact, not a live one

Every entry carries one of three markers, and the legend defines them precisely: pushed within 3 months, pushed 3 to 12 months ago, and no push for over 12 months. The API Compatibility section shows all three states side by side, with japicmp and Roseau marked as recent and Revapi in the middle band. The important detail is not the thresholds but when the comparison happens. Those dots were computed by the generator during the last run, so a green mark means the project had a push inside three months of the build, not that it has one today. Nothing re-renders them. That makes the dot a useful filter with a shelf life equal to the age of the file, and it explains the second rule in the header, which says that entries spanning several repositories use the most recent push for activity. A maintained fork can therefore keep a quiet parent repository looking active, because the newest push anywhere in the group wins. If a project matters to you, the dot is a starting point, not a verdict.

Multi repository entries get summed stars and a licence only on agreement

The header states the aggregation rule in one sentence, and it has consequences in both directions. For entries that span several repositories, the stars are combined, the most recent push is used for activity, and a licence is shown only when all the repositories agree. Read that as three warnings. First, a star count on a multi repository entry is a sum and is not comparable with a single repository entry, so sorting by stars across the list mixes two different quantities. Second, a missing licence chip does not mean the project has no licence, it means the repositories in the entry do not agree on one, which is a very different thing to act on. Third, an active fork can prop up a stale entry as described above. The single repository entries have no such ambiguity, which is why the small ones are easier to reason about: Roseau at 41 stars with an MIT chip and a recent push tells you exactly one thing about a project's licence, and a multi repository entry cannot.

Licence chips come from GitHub metadata and they are not all permissive

The chips are labelled as using GitHub SPDX metadata when available, so they are a read of what a repository declares rather than a legal review of its licence file. The spread across the visible categories is the point. ArchUnit, japicmp and Revapi carry Apache-2.0, Roseau and Taikai carry MIT, and jQAssistant, the Neo4J based static analysis tool, carries GPL-3.0. A list that mixes permissive and copyleft entries under one heading is doing you a favour by showing the chip, and a bad turn if you filter on the repository's overall licence. GPL-3.0 obligations do not disappear because the tool sits in a curated list, and the chip's dependency on GitHub metadata means a repository whose licence file and its configured metadata disagree will be labelled from the metadata. For anything that ends up in a shipped product, open the LICENSE file in the project you are actually adopting.

Star counts are rounded, and nothing says which entries the author has used

The numbers people scan first are rounded. ArchUnit shows as 3.8k and AgentScope Java as 5.7k, while jQAssistant shows 292 and Taikai 256, Roseau 41, Anahata ASI 27, WireDoctor 8 and ARA 6. A rounded thousand is fine for triage and useless for a close comparison, and the list places six star and eight star projects next to projects in the thousands without any marker separating curation from discovery. Each entry gets exactly one sentence of description, and that sentence is the only editorial content: japicmp compares two library JARs and reports source and binary incompatible changes, ArchUnit is a test library for specifying and asserting architecture rules, Dokimos is an evaluation framework that catches quality regressions in CI. There is no adoption note, no recommendation and no indication of who has run any of it. So the honest use of this list is as a supply of candidates with a description to scan, followed by your own evaluation of the two or three that survive.

One branch, no releases, and a snapshot that ages at a fixed rate

Maintenance of the list itself is simple to state. The repository is not archived, the default branch is `main`, the last push was on 2026-09-23, and it publishes no GitHub releases, so there is no version to pin and no changelog to read. Since the entire value of the file is the freshness of its metadata, the question for a reader is when the generator last ran rather than when the last commit landed, and the header does not print a build timestamp. Treat the numbers as a snapshot with a date attached to the commit you read, and re-check the handful of entries you intend to adopt. There is also a discoverability problem worth naming plainly: the repository has no homepage field and the list competes for a name that is also an ordinary adjective, so finding it means searching for the repository rather than the phrase. The resources section is the durable part of the answer, since communities, books and websites do not go stale the way a star count does.

Editorial conclusion

Use awesome-java as a map of the Java ecosystem, to find the category your problem lives in and then check the two or three candidates that matter, not as a ranking. Do not treat its star counts, licence chips or green dots as current facts, because all three were computed when the file was last generated, and a missing chip means the upstream repositories disagreed rather than that a project is permissively licensed. Before you adopt anything it points at, check three things on the upstream repository itself: the last commit date, the licence file rather than the GitHub metadata, and whether the project still supports the Java version you are on.

Frequently asked questions

Official sources

1. Official README
2. Project repository