Files
aego/docs/contributing.md
T
sanspie e54364070c
ci-platforms / windows amd64 smoke (push) Skipped
ci-platforms / darwin arm64 smoke (push) Skipped
github-native / gitea-pending (push) Skipped
github-native / darwin amd64 native (push) Skipped
github-native / linux amd64 native (push) Skipped
github-native / windows amd64 native (push) Skipped
github-native / darwin arm64 native (push) Skipped
github-native / gitea-result (push) Skipped
ci / checks (push) Failing after 23s
ci / native-authoring (push) Skipped
ci / build (amd64, linux, ubuntu-24.04) (push) Successful in 11m23s
ci / release (push) Skipped
ci-platforms / darwin amd64 smoke (push) Skipped
ci: speed up checks without reducing coverage
2026-11-15 20:54:53 +03:00

3.6 KiB

Contributing

Build and run

bash tools/bootstrap-native.sh
make cli
.cache/bin/aego edit examples/platformer

make res regenerates icons, previews and ES shaders; make golden-update rewrites golden images after an intended UI change.

Check levels

Level When Command
1 after a Go edit make quick: build and short tests selected from the current host's Go dependency graph
2 before a commit make affected, plus make check-camera, check-audio, check-gameplay, check-mutate, check-editor, check-web or check-docs for the areas you touched, and make golden after UI changes
3 before a push or a tag make ci

tools/affected.sh [base] lists host Go packages (default base origin/master, uncommitted files included). It rejects non-Go changes, nested modules, deleted packages, shallow checkouts and incomplete dependency graphs instead of silently reporting success. It does not cover other platforms, build tags, browsers or asset-specific gates; run the relevant checks and the full make ci in a protected snapshot. The CI server always runs the full make ci.

make ci-fast runs infrastructure and web-policy unit tests only. For one focused set, use make ci-suite SUITE=integration-race, studio-core, component-try, gl, web, web-gpu, web-materials, web-lighting, web-particles, stage12-release, remote-examples, editor, nonative, lint, depcheck or infra. Some suites generate files and must run in a protected snapshot. Neither shortcut is full acceptance; make ci-full is an alias for make ci.

Rules for engine code

  • Modules talk through contracts. A module never imports another module: shared types and services live in contracts/ (physics2d, camera2d, scriptcall, signals, debugdraw, …). tools/depcheck enforces the import rules; an exception goes into tools/depcheck/exceptions.txt with its file and reason.
  • Kernel stays neutral. Kernel, editor and sdk never name a built-in module, its components or its diagnostic codes in string literals; names come from the module catalog.
  • Every component has a Try it scene. It lives at res/docs/try/<Component>.aescene (with <Component>.aes and prefabs next to it when needed), shows the component's own effect and runs without warnings; aego docs check fails without it.
  • Internal state is not a component. Controller state lives in unexported fields of the component it belongs to or in a world service. A component that exists only to carry state for a service is registered Hidden: it is not in Create, Add Component, Try it or the docs.
  • Requirements add, they do not block. Declare Requires; Add Component, scene add-comp, Paste and presets add the missing components in the same undo step.
  • Every diagnostic code has a page with an example. Component codes (CAM, AUD, GMP, PHY, …) also have an example scene that produces the code; aego docs check fails without one. Asset codes say scope: asset, codes that only an edit during Play produces say scope: play.
  • Nodes are labelled, not pathed. UI shows nodes with props.NodeLabel (icon and name, the path in the tooltip).
  • Editor edits go through history. Every edit is a history command, normally commands.Mutation, so Undo, the Play changes diff and agents see it.
  • Hot paths do not allocate. Systems, mixers and controllers allocate nothing per frame; add testing.AllocsPerRun checks and a benchmark next to new hot code.

Commits

One commit per sub-stage, named Stage <n><x>: <what>; decisions go into ARCHITECTURE.md as D<number> in the same commit.