docs: take the coordinates and the API baseline to 1.0.0 - #44
Merged
Conversation
1.0.0 shipped at 17:59 on 2026-08-03 and carries the chunk, instance and shared instance work. The README still told readers to depend on 0.3.0, which is the release before any of it. apiBaselineVersion moves with it, and that is the part worth reading. Raising it made the build fail on purpose: api-breaks.properties declares accepted API breaks against baseline 0.3.0, but apiBaselineVersion is 1.0.0. Every exception in that file was judged against the older baseline and excludes its type from the check entirely, so each one has to be re-examined and either deleted or re-justified before the version moves. That is what the baseline key exists for. The one exception in the file -- FalcoLightingChunk becoming final under US-3.06 -- was a break against 0.3.0 and is not one against 1.0.0, because 1.0.0 is the release that shipped it. It is deleted rather than carried forward, and japicmp compares the class again: checked by making it package-private, which now fails the build, and reverted. The README's performance section said every figure comes from a JMH benchmark. One no longer does -- the 25 objects and 840 bytes of a fresh chunk are a jol count, with no spread and no statement about speed. It is marked as such where it appears, together with the fact that the instance benchmarks have never been run as a baseline, so no timing about this work is quoted anywhere. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NGpJqdmh7ZNH487GLqPJmK
The wiki gained a usage page for the instance module, and a page is the one place where an example can rot without anything noticing. This compiles every code block on it: the builder, the chunk loader form, the light engine combination, both lifecycle routes, the shared world, and the read-only storage accessors. It found one error while being written. The light engine block said `new ChunkLightScheduler(instance)`; the constructor takes a `ChunkLightService` and there is no overload for an instance, so the snippet as first written would not have compiled for anyone who copied it. The class is never run and asserts nothing. Its whole value is failing to compile, which was checked by breaking one line and watching :falco-demo:compileTestJava fail, then reverting. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NGpJqdmh7ZNH487GLqPJmK
Contributor
Test results 285 files 285 suites 8m 14s ⏱️ Results for commit c331c21. ♻️ This comment has been updated with latest results. |
…nippets The quick start built a server from falco-anvil and falco-light and mentioned falco-instance only in prose. A reader following it never saw the module that gives the world a chunk which allocates what it uses, cleans up when it is unregistered, and can carry Falco's light on the same class -- which is the combination the whole rewrite was for and which did not exist before 1.0.0. Step 1 now declares the BOM and all three modules; the readme is where somebody starts, and one pinned version for three artefacts is the thing to start with. Step 5 is new and shows them together: loader, scheduler supplier, and the builder form that closes the loader after saving, which is the part that is easy to get wrong by hand because a loader closed before the save loses it. It also names the two things that surprise people: getSections() materialises all 24 sections because a caller may write into the result, and a chunk supplier producing anything but a FalcoChunk is refused. And it says that Minestom's own events still fire, so nobody rewrites a working GlobalEventHandler listener. Every snippet of the quick start and of the wiki usage page is now compiled by DocumentationSnippets in falco-demo, renamed from WikiSnippetCheck because it covers both documents. Checked by breaking a line and watching :falco-demo:compileTestJava fail. The wiki called the quick start "four-step" in three places; it has five now. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NGpJqdmh7ZNH487GLqPJmK
The quick start walks somebody to a running server, which is what a quick start
is for -- and it left most of Falco invisible. A reader finished it without ever
seeing that the anvil loader has a builder, that it counts what it could not
resolve instead of failing, that the light engine does sky light and incremental
updates, that the scheduler can be driven from a plain container, or that a
chunk can be read without materialising its sections.
A new section after the quick start lists the rest, grouped by module, each with
the shortest snippet that shows it:
falco-anvil the builder, compression, save parallelism, data version,
and diagnostics -- the counters that say a world contained
blocks or biomes this loader substituted
falco-light calculate, calculateSky, calculateWithNeighbours, blockLightAt;
the scheduler builder with executor, area size, cache size and
sky-light mode; ChunkLightListener for a plain container; and
markChanged/markDirty for changes made outside Falco
falco-instance the four parts an instance delegates to, the read-only storage
accessors, lifecycle listeners, and the generator that writes
into clones so a failure leaves the chunk untouched
Every snippet is compiled by DocumentationSnippets, which now covers the quick
start, this overview and the wiki usage page, grouped by which document each
block belongs to. That mattered here: the overview is thirteen new snippets
against an API nobody had written against before, and compiling them is the only
reason to believe them.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NGpJqdmh7ZNH487GLqPJmK
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
1.0.0shipped at 17:59 today and carries the chunk, instance and shared instance work. The README still told readers to depend on0.3.0— the release before any of it.The part worth reviewing
apiBaselineVersionmoves to1.0.0, and raising it made the build fail on purpose:That is what the
baselinekey is for. The one exception in the file —FalcoLightingChunkbecomingfinalunder US-3.06 — was a break against0.3.0and is not one against1.0.0, because1.0.0is the release that shipped it. It is deleted rather than carried forward.Checked rather than assumed: with the exception gone,
checkApiCompatibilityis green against1.0.0; makingFalcoLightingChunkpackage-private then fails the build, so japicmp really is comparing the class again instead of skipping it. Reverted.The README
Coordinates go to
1.0.0(falco-anvil,falco-light, and thefalco-instanceline in the prose).The performance section claimed every figure comes from a JMH benchmark. One no longer does: the 25 objects and 840 bytes of a fresh chunk are a jol count — no spread, no statement about speed. It is now marked as such where it appears, along with the fact that the instance benchmarks exist but have never been run as a baseline, which is why no timing about this work is quoted anywhere in the file.
Wiki
Updated in the same pass, separately (
Falco.wiki@a61b6fband the follow-up): module coordinates, the BOM snippet —1.0.0is the first release that carriesfalco-bom, so the snapshot workaround and the comment explaining it are gone — the snapshot version, and the file quotes in Build Setup and Versioning and Releases. Historical statements dated to0.3.0("carried out on 2026-08-01 against Falco 0.3.0") were left alone.