Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(api): the tier has to reach the creator, and 0.50 has to answer for it

yhhd0a45f4655cd
diff --git a/VERSIONING.md b/VERSIONING.md
index 84974fc8a..eea05480e 100644
--- a/VERSIONING.md
+++ b/VERSIONING.md
@@ -34,7 +34,31 @@ A MAJOR bump is triggered by a breaking change to **any** of these:
Things that are explicitly **not** part of the public API and may change in any
release: internal C++ headers under `src/`, unexported SDK internals, editor
internals, the embedded origin signatures (see [PROVENANCE.md](PROVENANCE.md)),
-private fields, and anything marked `@internal` or `experimental`.
+private fields, and anything marked `@internal` or `@experimental`.
+
+## Stability tiers
+
+Surface 1 is large, and not all of it is equally settled. Every exported symbol
+carries exactly one tier, written as a JSDoc tag on its declaration — so it
+reaches the `.d.ts` your project compiles against, and your editor shows it on
+hover. `sdk/etc/*.api.md` is the full inventory.
+
+| Tier | Tag | What we promise |
+| --- | --- | --- |
+| Stable Candidate | `@public` | We expect 1.0 not to break it. Changing or removing one requires a deprecation release first. |
+| Beta | `@beta` | Shipping and supported, but the shape may still adjust before 1.0. |
+| Experimental | `@experimental` | No compatibility claim. It may change or disappear in any release. |
+| Internal | `@internal` | Not for you to depend on; it is a policy error for one to be exported at all. |
+
+**There is no stable-by-default.** An untagged symbol is `@experimental`:
+freezing is something a maintainer decides, never something they forget to
+prevent. A symbol reaches `@public` only after it is documented, pinned by a
+test, and used by one of the games we certify releases against.
+
+These tiers are enforced, not just described — `tools/api-surface.mjs` and
+`tools/check-freeze-bar.mjs` run on every push, and `--check-baseline` compares
+the tree against the last release tag so a broken `@public` promise fails the
+build rather than being noticed by whoever upgrades.
## Pre-1.0 (the `0.x` line)
@@ -50,13 +74,17 @@ Estella is currently in the `0.x` series. Plain SemVer allows anything to change
We will release **1.0.0** when the SDK API and the project format are stable enough
to promise full MAJOR-line compatibility. From 1.0.0 onward, standard SemVer applies
-(breaking changes require a MAJOR bump).
+(breaking changes require a MAJOR bump). Reaching it means moving APIs up the
+tiers above until the ones a game is built out of are all Stable Candidate; the
+tier table is how you can see how far along that is at any point.
## Deprecation & migration
- We **deprecate before we remove**. A deprecated API keeps working and emits a
warning (a console/log warning in the SDK; a `@deprecated` tag in the types) for
- at least one MINOR release before removal.
+ at least one MINOR release before removal. For `@public` this is a build rule,
+ not an intention: removing one that was not `@deprecated` in the previous
+ release fails `api-surface --check-baseline`.
- **Project files migrate forward automatically.** When the format changes, the
editor upgrades older projects on open and records the format version in the file
so the migration is deterministic and one-way within a MAJOR line.
@@ -69,7 +97,7 @@ to promise full MAJOR-line compatibility. From 1.0.0 onward, standard SemVer app
- The `esengine` SDK is **not published to npm**. It ships inside the editor (every
project created by the editor builds against the bundled SDK), so the Estella
release version is the single product version. The SDK's public API surface is
- snapshotted in `sdk/etc/*.api.md` and governed by release tags (`@beta`,
- `@internal`) — see `tools/api-surface.mjs`.
+ snapshotted in `sdk/etc/*.api.md` and governed by the release tags above — see
+ `tools/api-surface.mjs`.
- Pre-releases use SemVer pre-release suffixes (e.g. `v0.15.0-rc.1`) and are not
covered by the compatibility promises above.
diff --git a/tools/api-surface.mjs b/tools/api-surface.mjs
index 654c3f341..19c1a2b96 100644
--- a/tools/api-surface.mjs
+++ b/tools/api-surface.mjs
@@ -25,7 +25,7 @@
import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { join, relative } from 'node:path';
-import { ROOT, SDK, ETC, ts, ENTRIES, createSdkProgram } from './lib/sdkProgram.mjs';
+import { ROOT, SDK, ETC, ts, ENTRIES, createSdkProgram, leadingDoc } from './lib/sdkProgram.mjs';
import { TIERS, parseSnapshot, baselineFindings } from './lib/apiSnapshot.mjs';
const MODES = ['--check', '--update', '--check-dts', '--check-baseline'];
@@ -358,16 +358,30 @@ if (fromDts) {
continue;
}
const emitted = new Map();
+ const declared = new Map();
for (const symbol of checker.getExportsOfModule(moduleSymbol)) {
if (symbol.name.startsWith('__')) continue;
const desc = describeSymbol(symbol.name, symbol);
- if (desc) emitted.set(desc.name, desc.kind);
+ if (!desc) continue;
+ emitted.set(desc.name, desc.kind);
+ const resolved = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+ if (resolved.declarations?.[0]) declared.set(desc.name, resolved.declarations[0]);
}
// Only name and kind are compared: a tier can come from a `@file` header,
// and a header cannot survive into a bundled .d.ts.
const snapshot = parseSnapshot(readFileSync(join(ETC, `${entryName}.api.md`), 'utf8'));
+ // A freeze the creator's editor cannot show them is not a promise they
+ // can act on, and a dropped tag is invisible without something asking.
+ for (const [name, s] of snapshot) {
+ if (s.tier !== 'public') continue;
+ const decl = declared.get(name);
+ if (decl && !/@public\b/.test(leadingDoc(decl))) {
+ errors.push(`R5: '${name}' is @public but the built ${entryName}.d.ts does not carry the tag`);
+ }
+ }
+
const dropped = [...snapshot.keys()].filter((n) => !emitted.has(n));
const extra = [...emitted.keys()].filter((n) => !snapshot.has(n));
const rekinded = [...snapshot].filter(([n, s]) => emitted.has(n) && emitted.get(n) !== s.kind);
diff --git a/tools/check-freeze-bar.mjs b/tools/check-freeze-bar.mjs
index c5dc22b68..5fb760fe7 100644
--- a/tools/check-freeze-bar.mjs
+++ b/tools/check-freeze-bar.mjs
@@ -25,7 +25,7 @@
*/
import { readFileSync, readdirSync, existsSync } from 'node:fs';
import { join, relative } from 'node:path';
-import { ROOT, SDK, ETC, ts, ENTRIES, createSdkProgram } from './lib/sdkProgram.mjs';
+import { ROOT, SDK, ETC, ts, ENTRIES, createSdkProgram, leadingDoc, docProseLines } from './lib/sdkProgram.mjs';
import { parseSnapshot } from './lib/apiSnapshot.mjs';
import { GOLDEN, projectDir } from './goldenProjects.mjs';
@@ -56,30 +56,9 @@ function frozenSymbols() {
// Documented
// ---------------------------------------------------------------------------
-/** The node a doc comment attaches to — for `export const x`, the statement. */
-function docAnchor(decl) {
- let node = decl;
- if (ts.isVariableDeclaration(node) && node.parent?.parent) node = node.parent.parent;
- return node;
-}
-
-/**
- * A leading `/** *\/` block carrying at least one line that is not a tag.
- * Read from source text rather than the AST helpers so it says the same thing
- * about a declaration however TypeScript reshuffles its JSDoc accessors.
- */
+/** A leading doc block carrying at least one line that is not a tag. */
function hasDocProse(decl) {
- const node = docAnchor(decl);
- const text = node.getSourceFile().getFullText();
- for (const range of ts.getLeadingCommentRanges(text, node.getFullStart()) ?? []) {
- const comment = text.slice(range.pos, range.end);
- if (!comment.startsWith('/**')) continue;
- const prose = comment.split('\n')
- .map((l) => l.replace(/^\s*\/?\*+\/?/, '').replace(/\*\/\s*$/, '').trim())
- .filter((l) => l && !l.startsWith('@'));
- if (prose.length) return true;
- }
- return false;
+ return docProseLines(leadingDoc(decl)).length > 0;
}
// ---------------------------------------------------------------------------
diff --git a/tools/lib/sdkProgram.mjs b/tools/lib/sdkProgram.mjs
index d89fe6459..143d5fa47 100644
--- a/tools/lib/sdkProgram.mjs
+++ b/tools/lib/sdkProgram.mjs
@@ -19,6 +19,36 @@ export const ETC = join(SDK, 'etc');
export const ts = createRequire(join(SDK, '/'))('typescript');
+/** The node a doc comment attaches to — for `export const x`, the statement. */
+function docAnchor(decl) {
+ let node = decl;
+ if (ts.isVariableDeclaration(node) && node.parent?.parent) node = node.parent.parent;
+ return node;
+}
+
+/**
+ * The `/** *\/` blocks immediately above a declaration, as raw text. Read from
+ * source rather than the AST's JSDoc accessors so it answers the same way for a
+ * hand-written source file and a bundler's re-printed declaration.
+ */
+export function leadingDoc(decl) {
+ const node = docAnchor(decl);
+ const text = node.getSourceFile().getFullText();
+ const out = [];
+ for (const range of ts.getLeadingCommentRanges(text, node.getFullStart()) ?? []) {
+ const comment = text.slice(range.pos, range.end);
+ if (comment.startsWith('/**')) out.push(comment);
+ }
+ return out.join('\n');
+}
+
+/** Lines of a doc block that are neither delimiters nor tags. */
+export function docProseLines(doc) {
+ return doc.split('\n')
+ .map((l) => l.replace(/^\s*\/?\*+\/?/, '').replace(/\*\/\s*$/, '').trim())
+ .filter((l) => l && !l.startsWith('@'));
+}
+
/** Typed public entries (mirrors package.json "exports" + rollup dtsBuilds). */
export const ENTRIES = {
'index': 'src/index.ts',
diff --git a/tools/releaseGate.mjs b/tools/releaseGate.mjs
index 97b2d90a2..e0481500c 100644
--- a/tools/releaseGate.mjs
+++ b/tools/releaseGate.mjs
@@ -15,7 +15,7 @@
* This says the criteria are OWNED. Whether they PASS is what running them says.
*/
-export const RELEASE = '0.49';
+export const RELEASE = '0.50';
/**
* `answeredBy` is a shell command run from the repo root; `needs` are the files
@@ -152,6 +152,33 @@ export const CRITERIA = [
// artifact CI produces and cannot then run as a user would.
manual: 'release captain, on the downloaded build: Help → Export Diagnostics',
},
+ {
+ id: 'frozen-api-earned',
+ says: 'every @public symbol is documented, pinned by a test, and called by a golden project',
+ answeredBy: 'node tools/check-freeze-bar.mjs',
+ needs: ['tools/check-freeze-bar.mjs', 'tools/goldenProjects.mjs'],
+ },
+ {
+ id: 'frozen-api-kept',
+ says: 'the @public promises the last release shipped are all still kept',
+ answeredBy: 'node tools/api-surface.mjs --check-baseline',
+ needs: ['tools/api-surface.mjs', 'tools/lib/apiSnapshot.mjs'],
+ },
+ {
+ id: 'tiers-reach-the-creator',
+ says: 'the stability tier is in the .d.ts a project compiles against, not only in our snapshot',
+ // The 17 @beta symbols index claimed while the built declarations carried 3
+ // is what this is for: a tier nobody can see is a tier nobody can act on.
+ answeredBy: 'node tools/api-surface.mjs --check-dts',
+ needs: ['tools/api-surface.mjs', 'tools/lib/sdkProgram.mjs'],
+ },
+ {
+ id: 'creator-can-say-what-is-safe',
+ says: 'the docs name the four tiers and which APIs are in each, in both languages',
+ // What a tier MEANS is a promise to people, and the sentence making it is
+ // not something to compute from a snapshot.
+ manual: 'release captain, over docs/astro: the stability page matches sdk/etc and VERSIONING.md',
+ },
{
id: 'no-p0-packaging-bugs',
says: 'no open P0 against packaging or launch',