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(gates): a feature that ships without a note fails the build
esengine4d4bbd55e91a
diff --git a/tools/check-changelog-covers.mjs b/tools/check-changelog-covers.mjsnew file mode 100644index 000000000..b93d9dccb--- /dev/null+++ b/tools/check-changelog-covers.mjs@@ -0,0 +1,105 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Every user-facing commit reaches the release notes, or says why not.+ *+ * See tools/releaseNotes.mjs for why this exists. The short version: the other+ * CHANGELOG gate reads structure, this one reads whether anything was left out.+ */+import { execFileSync } from 'node:child_process';+import { readFileSync, existsSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { NOTED, NOTES_FLOOR } from './releaseNotes.mjs';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const CHANGELOG = path.join(ROOT, 'CHANGELOG.md');++/** Types whose commits change what a creator can do, so a note is owed. */+const USER_FACING = /^(feat|fix|refactor|perf)(\([^)]*\))?!?:/;++const git = (args, cwd = ROOT) => {+ try {+ return execFileSync('git', args, { cwd, encoding: 'utf8' });+ } catch {+ return '';+ }+};++/**+ * Subjects between `from` and `to` in one repository. The submodule is read at+ * the gitlinks the two revisions point at — its commits are the editor's, and a+ * creator cannot tell which repository a feature came from.+ */+function subjects(from, to, cwd = ROOT) {+ return git(['log', '--format=%s', `${from}..${to}`], cwd)+ .split('\n').map((l) => l.trim()).filter(Boolean);+}++const gitlinkAt = (rev) => {+ const line = git(['ls-tree', rev, 'desktop']).trim();+ return line ? line.split(/\s+/)[2] : '';+};++const problems = [];+const unclassified = [];++if (!existsSync(CHANGELOG)) {+ console.error('check-changelog-covers: no CHANGELOG.md');+ process.exit(1);+}+const changelog = readFileSync(CHANGELOG, 'utf8');++// Everything since the floor, HEAD included: a feature is owed a note from the+// moment it lands, not from the moment somebody cuts a release.+const commits = [+ ...subjects(NOTES_FLOOR, 'HEAD').map((s) => ({ subject: s, repo: 'engine' })),+];+const desktop = path.join(ROOT, 'desktop');+const [fromLink, toLink] = [gitlinkAt(NOTES_FLOOR), gitlinkAt('HEAD')];+if (fromLink && toLink && existsSync(path.join(desktop, '.git'))) {+ commits.push(...subjects(fromLink, toLink, desktop).map((s) => ({ subject: s, repo: 'editor' })));+}++let noted = 0;+let internal = 0;+for (const { subject, repo } of commits) {+ if (!USER_FACING.test(subject)) continue;+ const entry = NOTED[subject];+ if (!entry) {+ unclassified.push(`${repo}: ${subject}`);+ continue;+ }+ if (entry.internal) {+ internal++;+ continue;+ }+ // The other direction: a headline that no longer exists means the note was+ // renamed or dropped, and the classification stopped describing the release.+ if (!changelog.includes(entry.note)) {+ problems.push(`"${subject}" says it landed under "${entry.note}", which is not in the CHANGELOG`);+ continue;+ }+ noted++;+}++for (const key of Object.keys(NOTED)) {+ if (!commits.some((c) => c.subject === key)) {+ problems.push(`nothing since ${NOTES_FLOOR} carries "${key}" — the entry names no commit`);+ }+}++if (unclassified.length) {+ console.error(`check-changelog-covers: ${unclassified.length} user-facing commit(s) reach no note.`);+ console.error('Add each to tools/releaseNotes.mjs — the note it landed under, or why a creator cannot see it:\n');+ for (const u of unclassified) {+ console.error(` '${u.replace(/^[a-z]+: /, '').replace(/'/g, "\\'")}':`);+ console.error(" { note: '' }, // or { internal: '<why no creator can observe it>' }");+ }+ console.error('');+}+for (const p of problems) console.error(` ${p}`);++if (unclassified.length || problems.length) process.exit(1);+console.log(`check-changelog-covers: ${noted} user-facing commit(s) landed in a note`+ + ` and ${internal} said why they could not, since ${NOTES_FLOOR}.`);diff --git a/tools/gates.mjs b/tools/gates.mjsindex 55a675590..1378ce34d 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -249,6 +249,10 @@ export const GATES = [{ id: 'verifier-exit', run: 'node tools/check-verifier-exit.mjs', needs: 'editor' },{ id: 'render-scenes', run: 'node tools/check-render-scenes.mjs' },{ id: 'release-metadata', run: 'node tools/check-release-metadata.mjs' },+ // The other half: metadata reads the CHANGELOG's shape, this reads whether+ // anything shipped without reaching it. Three releases running lost features+ // that only a hand-read of `git log` found.+ { id: 'changelog-covers', run: 'node tools/check-changelog-covers.mjs', needs: 'editor' },// A published desktop artifact has one name, declared, whitespace-free, and// still distinct once the asset store has normalised it.{ id: 'release-artifact-names', run: 'node tools/check-release-artifact-names.mjs', needs: 'editor' },diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsnew file mode 100644index 000000000..6d0a9be98--- /dev/null+++ b/tools/releaseNotes.mjs@@ -0,0 +1,127 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Where every user-facing commit landed in the release notes.+ *+ * `check-release-metadata` reads the CHANGELOG's STRUCTURE — that a version has+ * a section, a compare link, a supported row. Nothing read its CONTENT, so a+ * feature could ship with no note and the release would still go out green. It+ * has happened in three releases running: v0.55 lost 31 commits across two+ * batches, 0.64 lost three, 0.66 lost the whole ECS speculation line plus the+ * editor crash fix — each found only by reading `git log` by hand.+ *+ * So say it once per commit instead. A commit that changes what a creator can+ * do names the note it landed under; one that does not says why. The gate holds+ * both directions: a missing commit fails, and so does a note title that no+ * longer exists in the CHANGELOG, which is what a rename would otherwise do+ * quietly.+ */++/** The release this reaches back to. Older ones are out of scope BY DECLARATION. */+export const NOTES_FLOOR = 'v0.65.0';++/**+ * Commit subject → where it landed. `note` is a CHANGELOG headline (a prefix of+ * one is enough); `internal` is the reason a creator could not observe it.+ *+ * Subjects, not hashes: a rebase changes the hash and the line it names is what+ * the reader recognises anyway.+ */+export const NOTED = {+ // — after 0.66.0 —+ 'feat(gates): a feature that ships without a note fails the build':+ { internal: 'a gate over this repository\'s own release process — a creator'+ + ' downloads the engine, not the checks that decided it could ship' },++ // — 0.66.0, engine —+ 'feat(assets): the shapes a model was authored to blend between arrive with it':+ { note: 'A model brings the shapes it can be blended towards.' },+ 'feat(render): a mesh is drawn in the shape its weights ask for':+ { note: 'A model brings the shapes it can be blended towards.' },+ 'feat(anim): a clip can say what shape a mesh is in':+ { note: 'A model brings the shapes it can be blended towards.' },+ 'feat(assets): an FBX brings its blend shapes':+ { note: 'A model brings the shapes it can be blended towards.' },+ 'feat(assets): a list field can say where its row names come from':+ { note: 'A model brings the shapes it can be blended towards.' },+ 'feat(anim): a controller is a STACK of machines, not one':+ { note: 'A controller is a stack of machines, not one.' },+ 'feat(anim): the graph ops address a layer, without a second vocabulary':+ { note: 'A controller is a stack of machines, not one.' },+ 'feat(anim): a layer writes the part of the rig it was given':+ { note: 'A layer writes the part of the rig it was given.' },+ 'feat(anim): a silent layer says nothing, including with a sprite sheet':+ { note: 'A layer writes the part of the rig it was given.' },+ 'feat(anim): a 1D blend mixes its neighbours instead of picking one':+ { note: 'A blend mixes its neighbours instead of picking one.' },+ 'feat(anim): a blend over a plane, by the operation the line already used':+ { note: 'A blend over a plane.' },+ 'feat(examples): the third-person rig runs and swings at the same time':+ { note: 'The third-person rig runs and swings at the same time.' },+ 'feat(anim): a clip means the same thing on a rig bound differently':+ { note: 'A clip means the same thing on a rig bound differently.' },+ 'feat(anim): a retargeted step travels as far as the rig would':+ { note: 'A clip means the same thing on a rig bound differently.' },+ 'feat(anim): one clip drives rigs that do not share its bone names':+ { note: 'One clip drives rigs that do not share its bone names.' },+ 'feat(anim): the posed skeleton can be made to reach something':+ { note: 'The posed skeleton can be made to reach something.' },+ 'feat(anim): a constraint is an edit like any other':+ { note: 'The posed skeleton can be made to reach something.' },+ 'feat(ecs): a step of gameplay nobody has seen yet, and can take back':+ { note: 'A step of gameplay nobody has seen yet, and can take it back.' },+ 'feat(ecs): a system asks for a speculation the way it asks for anything else':+ { note: 'A step of gameplay nobody has seen yet, and can take it back.' },+ 'feat(ecs): a step can be asked whether it is a function of the world':+ { note: 'A step can be asked whether it is a function of the world.' },+ 'feat(net): the rule reconciliation replays can be asked whether it replays':+ { note: 'A step can be asked whether it is a function of the world.' },+ 'refactor(anim): a state says what it plays one way, from the file in':+ { note: 'A state says what it plays one way, from the file in.' },+ 'fix(anim): a layer\'s clips ship, and reach the game that plays them':+ { note: 'A layer\'s clips reach the game that plays them.' },+ 'fix(anim): a blend weights its displacement the way it weights its pose':+ { note: 'A blend weights its displacement the way it weights its pose.' },+ 'feat(anim): the blend twins are both on the public surface':+ { note: '`isBlend1D` was never on the public surface' },+ 'fix(golden): the editor\'s frame shares the rasterizer too':+ { internal: 'a verifier reading the editor\'s own capture — no packaged game changes' },+ 'fix(gates): the editor capture gets the settle window the package gets':+ { internal: 'a verifier\'s timing, not the engine\'s' },++ // — 0.66.0, editor —+ 'feat(inspector): a mesh\'s shapes are editable, under their own names':+ { note: 'A model brings the shapes it can be blended towards.' },+ 'feat(animator): the editor edits a layer, and says which one':+ { note: 'A controller is a stack of machines, not one.' },+ 'feat(animator): a blend is something an author can make':+ { note: 'A blend is something an author can make.' },+ 'refactor(animator): the panel asks one question about a motion, not four':+ { note: 'A state says what it plays one way, from the file in.' },+ 'feat(animator): constraints are something an author can place':+ { note: 'The posed skeleton can be made to reach something.' },+ 'feat(animator): an avatar can be described from the rig itself':+ { note: 'A clip means the same thing on a rig bound differently.' },+ 'feat(animator): an avatar measures the rig it describes':+ { note: 'A clip means the same thing on a rig bound differently.' },+ 'feat(project): an avatar is an asset the editor can make':+ { note: 'A clip means the same thing on a rig bound differently.' },+ 'fix(editor): a crash dialog must not hold the process it warns about':+ { note: 'An unexpected error no longer takes the editor with it.' },+ 'fix(play): step reports the frames that ran, and the checks start from a frozen world':+ { note: '`step` reports the frames that ran, not the number it was asked for.' },+ 'fix(checks): ready is not the physics module having arrived':+ { internal: 'an editor check\'s own synchronisation' },+ 'fix(checks): a four-minute step is a four-minute silence':+ { internal: 'an editor check\'s own synchronisation' },+ 'fix(checks): a file on disk is not the registry having adopted it':+ { internal: 'an editor check\'s own synchronisation' },+ 'fix(checks): let the 3D step finish, and say how long it took':+ { internal: 'an editor check\'s own budget' },+ 'fix(checks): "before" is a state the world was in, not seven moments':+ { internal: 'an editor check\'s own reading' },+ 'fix(checks): a name on the command line selects again':+ { internal: 'the check runner\'s argument parsing' },+ 'fix(automation): a capture waits as long as the package it is compared to':+ { internal: 'a verifier\'s timing, not the engine\'s' },+};