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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdindex 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 anyrelease: internal C++ headers under `src/`, unexported SDK internals, editorinternals, 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 changeWe will release **1.0.0** when the SDK API and the project format are stable enoughto 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 awarning (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, theeditor upgrades older projects on open and records the format version in the fileso 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 (everyproject created by the editor builds against the bundled SDK), so the Estellarelease 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 notcovered by the compatibility promises above.diff --git a/tools/api-surface.mjs b/tools/api-surface.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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',