Merge remote-tracking branch 'origin/main' into mm1-1447
# Conflicts: # .github/workflows/ci.yml
This commit is contained in:
@@ -4,6 +4,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor
|
||||
|
||||
## Build and run
|
||||
|
||||
- [AGENTS.md](../AGENTS.md) and [Architecture](architecture.md): where each part of the code lives, how `Game` is organised, which harness checks which area.
|
||||
- [Build from source](../README.md#build-from-source): your own copy of the game, resource preparation, `cargo run`.
|
||||
- [Native client](native-client.md): options, controls, the dedicated server, `horizon-ctl` scripting, packaging, architecture.
|
||||
- [Host a server](hosting.md): install `horizon-server`, prepare the game files, first run, `server.toml`, the commands, the web panel, backups, services and Docker; what works today and what doesn't yet.
|
||||
|
||||
@@ -71,7 +71,6 @@ passes on without checking it).
|
||||
| Dedicated server here: start, console, log, stop | Servers | yes | yes | yes | yes | `server`; MCP `server`, `server_command`, `server_log`, `server_stop` |
|
||||
| Hosted servers: list, create, set up, run a command, forget | Servers | yes | no | yes | yes | `servers ...`; `servers_forget` needs `confirm` |
|
||||
| Accounts: list, sign in, sign out, select, offline | Settings | yes | part | yes | yes | names and UUIDs only; sign-in is a device code; `account_offline` was missing |
|
||||
| Update channel (Alpha, Stable) | Settings | yes | yes | yes | yes | |
|
||||
| Game folder, server folder, install new versions, opening animation | Settings | no | no | yes | yes | `settings [KEY VALUE]` |
|
||||
| Extra game arguments | Settings | yes | no | yes | yes | `game-args` |
|
||||
| Applications menu entry (Linux) | Settings | yes | no | yes | yes | `desktop-entry` |
|
||||
@@ -148,7 +147,7 @@ The switch is in three places: Settings > AI in the launcher, Horizon Settings i
|
||||
| Companion (#1068) | uses the same switch (see horizon-parity companion-notes.md) |
|
||||
|
||||
Every other launcher command stays usable: versions, install, remove, prepare, play, server,
|
||||
notes, links, account, update-channel, settings, game-args, logs, update, desktop-entry, data,
|
||||
notes, links, account, settings, game-args, logs, update, desktop-entry, data,
|
||||
modpack, mods, servers, no-ai and benchmark. None of them drives the game for an agent. The
|
||||
launcher itself, packagers, the docs and players' scripts need them, and `no-ai` has to stay to
|
||||
turn the switch off.
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# Architecture: feature → files → checks
|
||||
|
||||
The 40 areas changed most often in the 30 days to 2026-10-23 (commits on main touching the area; `game.rs` is
|
||||
counted only for the game loop because nearly every gameplay change touches it). The crate map, how `Game` is
|
||||
organised and how to build and test are in [AGENTS.md](../AGENTS.md).
|
||||
|
||||
Paths: `L/` = `crates/horizon-client/src/`, `G/` = `crates/horizon-client/src/game/`, `W/` =
|
||||
`crates/horizon-world/src/`. Checks: a bare name is a harness (`python3 tools/parity.py <name>`, script
|
||||
`tools/test_<name>_parity.py`); `lan_e2e <check>` is `python3 tools/lan_e2e.py --check <check>`.
|
||||
|
||||
For the full set of harnesses a file can affect, ask the runner:
|
||||
`printf '%s\n' <paths> > /tmp/p.txt && python3 tools/parity.py --changed-files /tmp/p.txt --list`.
|
||||
Any file of the game binary (`game.rs`, `game/`) selects the ~25 harnesses that run the binary; a client lib
|
||||
file selects ~103.
|
||||
|
||||
| # | Area (commits) | Files | Checks |
|
||||
|---|---|---|---|
|
||||
| 1 | Game loop, tick order, frame pacing (554) | `L/game.rs` (`fn tick`, `fn tick_world`, `fn render`, `about_to_wait`), `L/clock.rs`, `L/window.rs`, `L/spans.rs` | game_loop, frame_limiter, interaction_input, tick |
|
||||
| 2 | Mobs in the game loop, spawning (166) | `G/creatures.rs`, `G/natural_spawning.rs`, `L/mobs/spawning.rs`, `L/mobs/spawn_rules.rs`, `L/mobs/spawn_selection.rs`, `L/mobs/finalize.rs`, `G/spawner.rs`, `G/trial_spawner.rs` | natural_spawn, spawn_rules, finalize_spawn, spawner, trial_spawner, mob_ai |
|
||||
| 3 | World save and load (163) | `L/save.rs`, `G/saving.rs`, `G/persist.rs` (entities), `L/entity_nbt.rs`, `L/block_entity_nbt.rs`, `W/region.rs`, `W/nbt.rs` | save_roundtrip, world_reopen, world, datafix |
|
||||
| 4 | World generation (153) | `W/worldgen.rs`, `W/worldgen/` (`generator*.rs`, `feature_graph.rs`, `structure/`, `placement/`), `L/vanillagen.rs` | chunk_generation, worldgen, server_world_gen, world_spawn, feature_graph, feature_placement, decoration and the other worldgen harnesses |
|
||||
| 5 | Multiplayer client, packets in (145) | `G/remote.rs` (`fn handle_packet`, `fn tick_remote`), `G/remote_*.rs`, `L/net.rs` | dedicated_server, server_entities, lan_e2e (all) |
|
||||
| 6 | Agent control, horizon-ctl (145) | `L/control.rs`, `L/bin/horizon-ctl/`, `G/control.rs`, `G/agent.rs`, `G/events.rs`, `G/ui_control.rs` | `python3 tools/agent_control_e2e.py`; `cargo test -p horizon-client --bin horizon-ctl` |
|
||||
| 7 | CI and release (134) | `.github/workflows/` (`ci.yml`, `parity.yml`, `release.yml`, `launcher.yml`), `tools/ci/`, `tools/parity.py`, `tools/pr_ready.py` | `python3 -m unittest discover -s tests`; actionlint (`.github/actionlint.yaml`) |
|
||||
| 8 | LAN host: connections, play state, tracking (133) | `L/lan/` (`conn.rs`, `hub.rs` + `hub/`, `chunks.rs`, `entity.rs`, `tracking.rs`, `guest.rs`, `playerdata.rs`), `G/lan.rs` | lan, lan_e2e (all), `cargo test -p horizon-client --test lan_bot` |
|
||||
| 9 | Renderer core (132) | `L/gfx.rs` (`Renderer::new`, `Renderer::render`), `L/gfx/` (cull, occlusion, translucency, upload, timing, lod) | client_graphics, culling_rays, translucency; `horizon-client --benchmark standard` |
|
||||
| 10 | Launcher (124) | `launcher/src/` (`main.rs`, `backend.rs`, `cli.rs`, `mcp.rs`, `servers_page.rs`) | `cd launcher && cargo test`; `python3 tools/launcher_mcp_e2e.py` |
|
||||
| 11 | Mob types and species (117) | `L/mobs.rs`, `L/mobs/species.rs`, `L/mobs/data.rs`, `L/mobs/living.rs`, `L/mobs/drops.rs`, `L/mobs/gear.rs` | mob_attributes, entity_attribute, entity_death_loot, mob_ai |
|
||||
| 12 | Guests' actions on a server (98) | `G/lan_actions.rs` (`fn as_guest`, `fn tick_guests`), `G/lan_{attributes,pvp,chat,crafting,stations,trading,mount_menu,waypoints}.rs` | server_player_combat, server_player_damage, server_player_targets, lan_e2e (all) |
|
||||
| 13 | Modpack porting, mod content (97) | `crates/horizon-port-pack/`, `L/mod_content.rs`, `tools/port_*.py`, `packs/` | `cargo test -p horizon-port-pack`; `python3 tools/mod_port_harness.py` |
|
||||
| 14 | Mob AI (96) | `L/mobs/ai.rs`, `goals.rs`, `brain.rs`, `*_brain.rs`, `nav.rs`, `path.rs`, `control.rs` | mob_ai (probe `examples/mob_ai_probe.rs`; known failure on main: drowned_*, #290) |
|
||||
| 15 | Items and item use (96) | `L/items.rs`, `L/item_data.rs`, `G/hand.rs`, `G/consume.rs`, `G/potions.rs`, `L/effects.rs`; game.rs `fn use_hand`, `fn use_item` | use_item_on, item_use, item_use_lifecycle, consumable, consume_effect, status_effect |
|
||||
| 16 | Options and settings screens (93) | `L/options_ui.rs`, `G/options.rs`, `L/settings.rs`, `L/options_file.rs`, `L/graphics_ui.rs`, `L/graphics.rs` | options, toggle_keys |
|
||||
| 17 | HUD, chat, tab list (93) | `L/hud.rs`, `L/hud_layout.rs`, `L/hud_overlays.rs`, `L/chat.rs`, `G/chat.rs`, `L/tab_list.rs`, `L/locator_bar.rs`, `G/locator_bar.rs` | hud, tab_list, locator_bar, chat_screen, secure_chat |
|
||||
| 18 | Command execution (88) | `G/commands.rs`, `G/commands/*.rs`, `L/scoreboard_cmd.rs`, `L/data_cmd.rs`, `G/functions.rs` | command_exec (corpus `tools/command_exec_corpus.py`), scoreboard, server_ops_feedback, lan_e2e commands |
|
||||
| 19 | Chunk streaming, light, tickets (85) | `L/streaming.rs`, `L/world.rs`, `L/chunk.rs`, `L/chunk_map.rs`, `L/light.rs`, `L/ticket_levels.rs`, `L/tick_chunk_membership.rs`, `G/world_loading.rs` | light, chunk_status, random_tick_sections; `cargo test -p horizon-client --test streaming_meshes` |
|
||||
| 20 | Mob models and animation (78) | `L/mobs/render.rs`, `L/mobs/anim.rs`, `L/mobs/body_anim.rs`, `L/mobs/keyframes.rs`, `L/entity.wgsl` | entity_model |
|
||||
| 21 | Block behaviour, server side (78) | `W/level/` (`mod.rs`, `tick.rs`, `hooks.rs`, `data.rs`, `redstone.rs`, `place.rs`), `G/block_entity_ticks.rs`, `G/moving_pistons.rs` | block_update, redstone, random_tick, simple_block, piston_movement, block_entity_tickers |
|
||||
| 22 | Player movement and collision (75) | `L/motion.rs` + `L/motion/`, `L/collisions.rs`, `W/entity_move.rs`, `W/player_travel.rs`, `W/collision.rs` | collision, entity_move, player_travel, living_motion, climbing, swimming; `python3 tools/test_native_scene_motion.py` |
|
||||
| 23 | Resource packs and models (65) | `L/packs.rs` + `L/packs/`, `L/pack_screen.rs`, `L/atlas_sources.rs`, `L/sprites.rs`, `L/model_library.rs`, `G/packs.rs`, `crates/horizon-assets/` | resource_pack, pack_selection, pack_screen, model_resolution, item_model, mipmap |
|
||||
| 24 | Container menus and inventory (61) | `L/menu.rs`, `L/container_screen.rs`, `L/containers.rs`, `L/creative.rs`; game.rs `fn menu_ops`, `fn click_inventory` | menu_click, container_screen, creative, lan_e2e containers clicks |
|
||||
| 25 | Workstations (60) | `L/stations.rs`, `G/stations.rs`, `L/enchant.rs`, `L/brewing.rs` | enchanting, screen_layout, lan_e2e brewing loom stonecutter grindstone anvil smithing |
|
||||
| 26 | Crafting and the recipe book (59) | `L/crafting.rs`, `L/recipe_book.rs`, `L/recipe_book_screen.rs`, `G/recipe_book.rs`, `G/machines.rs`, `G/machines/crafter.rs` | recipe, recipe_book, recipe_book_view, place_recipe, ghost_recipe, crafter |
|
||||
| 27 | Vehicles and mounts (54) | `G/boats.rs`, `G/minecarts.rs`, `G/mounts.rs`, `G/mount_menu.rs`, `G/llamas.rs`, `G/passengers.rs` | server_entities, lan_e2e boats minecarts riding mounts |
|
||||
| 28 | Villagers, trading, raids (50) | `L/mobs/villager*.rs`, `L/merchant.rs`, `G/trading.rs`, `G/villagers.rs`, `L/raid.rs`, `G/raids.rs`, `L/gossip.rs` | trading, raid, mob_ai |
|
||||
| 29 | Title, worlds, startup (49) | `L/title.rs` + `L/title/`, `G/startup_menu.rs`, `L/title_edition.rs` | world_options; `cargo test -p horizon-client --lib title` |
|
||||
| 30 | Dedicated server, horizon-server (48) | `G/dedicated.rs`, `G/dedicated/status.rs`, `crates/horizon-server/`, `crates/horizon-server-files/` | dedicated_server, server_files, user_cache, online_mode, server_ops_feedback |
|
||||
| 31 | Particles and client effects (46) | `L/particles.rs`, `G/render_tick.rs`, `G/level_particles.rs`, `L/animate_tick.rs` | particle_providers, block_particles, entity_particles, emitter_particles, marker_particles |
|
||||
| 32 | Bosses and the End (45) | `G/dragon.rs`, `G/wither.rs`, `G/end.rs` | server_dragon, end_podium, end_gateway |
|
||||
| 33 | Protocol and packets (44) | `crates/horizon-protocol/src/` (`packets/play.rs`, `entity_data.rs`, `connection.rs`) | dedicated_server, online_mode, secure_chat; `cargo test -p horizon-protocol` |
|
||||
| 34 | Multiplayer and LAN screens, friends (44) | `L/multiplayer.rs`, `G/lan_screen.rs`, `G/friends.rs`, `L/friends_screen.rs`, `crates/horizon-friends/`, `crates/horizon-relay/` | lan, world_options; `python3 tools/test_friends.py` |
|
||||
| 35 | Dispensers (43) | `G/dispenser.rs`, `G/dispense_fixture.rs` (the harness side) | dispenser |
|
||||
| 36 | Audio and music (38) | `L/audio.rs`, `L/sound_engine.rs`, `L/sound_events.rs`, `L/music.rs`, `G/music.rs`, `L/ambience.rs`, `G/subtitle_hud.rs` | sound_engine, sound_event, music, situational_music, ambient_sound, subtitle |
|
||||
| 37 | Integrated server and levels (34) | `G/integrated.rs`, `G/levels.rs`, `G/server_travel.rs` | server_dimension_players, `lan_e2e --server-thread` (portals, levels, distance, lava) |
|
||||
| 38 | Command parsing (34) | `L/command/` (`args.rs`, `selector.rs`, `tree_*.rs`, `vanilla.rs`) | command_parse (corpus `tools/command_parse_corpus.py`) |
|
||||
| 39 | Benchmarks and telemetry (34) | `L/benchmark.rs`, `tools/perf_bench.py`, `L/telemetry.rs`, `crates/horizon-telemetry*/`, `crates/horizon-bench/` | `python3 -m unittest tests.test_perf_bench`; [benchmark.md](benchmark.md) |
|
||||
| 40 | Explosions and TNT (31) | `G/explosion.rs`, `G/tnt.rs` | lan_e2e blast; no dedicated harness yet |
|
||||
@@ -130,16 +130,6 @@ Play offline, without an account.
|
||||
|
||||
MCP: `account_offline`.
|
||||
|
||||
## `horizon-launcher update-channel`
|
||||
|
||||
Show or set which Horizon releases install by themselves: stable (a tested build about once a day) or alpha (every release as soon as it is built; can break).
|
||||
|
||||
horizon-launcher update-channel [CHANNEL]
|
||||
|
||||
- `CHANNEL` (stable, alpha): Omit to show the current channel
|
||||
|
||||
MCP: `update_channel`.
|
||||
|
||||
## `horizon-launcher settings`
|
||||
|
||||
Show the launcher's settings, or set one (the Settings page): selected-version TAG, minecraft-dir PATH, server-dir PATH ("default" resets a folder), install-new-versions on|off, opening-animation on|off.
|
||||
|
||||
+41
-66
@@ -2,9 +2,8 @@
|
||||
|
||||
How a change gets from a pull request to players: the checks a pull request passes, how it merges, and the
|
||||
automatic releases that follow. Releases are automatic and frequent so the latest Horizon is always playable.
|
||||
Each one goes out as an **alpha** build, which launchers on the **Alpha** channel install at once, and becomes **stable** in
|
||||
the next daily promotion unless something holds it back ([Channels](#channels)): launchers and servers install
|
||||
stable builds unless their owner picks Alpha.
|
||||
There is one channel ([One channel](#one-channel)): each release is published as the release and GitHub's *latest*
|
||||
once its smoke test passed and no `release-blocker` is open, and launchers and servers install it at once.
|
||||
|
||||
## Pull request checks
|
||||
|
||||
@@ -101,12 +100,11 @@ flowchart LR
|
||||
windows["Windows x64<br/>GitHub windows-latest"]
|
||||
mac["macOS arm64<br/>Mac mini runner<br/>+ offscreen game run"]
|
||||
end
|
||||
build --> publish["publish vX.Y.Z as an alpha<br/>notes from the merged PRs"]
|
||||
publish --> alpha(["launchers on Alpha install it"])
|
||||
publish --> promote{"promote.yml, daily at 20:00 UTC:<br/>6 h old by then, smoke test, no release-blocker"}
|
||||
promote --> stable["stable and latest<br/>notes since the last stable"]
|
||||
stable --> launcher(["every launcher and server installs it"])
|
||||
stable --> kira(["Kira posts it;<br/>pings only with ### New"])
|
||||
build --> gate{"gate: the smoke test drew a world,<br/>no release-blocker is open"}
|
||||
gate -- no --> nothing(["nothing is published"])
|
||||
gate -- yes --> publish["publish vX.Y.Z as the release and latest<br/>notes from the merged PRs"]
|
||||
publish --> launcher(["every launcher and server installs it"])
|
||||
publish --> kira(["Kira posts it; the first release<br/>after 20:00 UTC pings, once a day"])
|
||||
```
|
||||
|
||||
### When it releases
|
||||
@@ -121,9 +119,10 @@ commits) since the last **published** game release:
|
||||
- It releases when at least one pull request counts and the newest of them merged at least 5 minutes ago, so a wave
|
||||
of merges becomes one release; if merges never pause, it releases once the oldest has waited 20 minutes. There is
|
||||
no minimum time between releases: every settled player-facing change ships, limited only by the release already
|
||||
building. That is the Alpha channel, many releases a day.
|
||||
building: many releases a day.
|
||||
- A pull request labelled `release-now` (a crash or a blocker) releases at once.
|
||||
- A pull request labelled `skip-release` (work players don't see) doesn't count and isn't listed in the notes.
|
||||
- An open issue labelled `release-blocker` holds every game release, forced ones too (`held by release-blocker #N`).
|
||||
- One release at a time (concurrency group `game-release`); a run that finds nothing new does nothing.
|
||||
- A scheduled or hand-started run releases main's newest commit whose `checks` passed; after `checks`, the commit
|
||||
they passed on.
|
||||
@@ -137,7 +136,7 @@ How releases are numbered, and how installs from before 0.2 reach it: [versionin
|
||||
the patch after the newest release tagged on that line (`v0.2.0` first). A `feature` label doesn't change the line:
|
||||
only that file does, by pull request.
|
||||
- Without the file (every release before 0.2), `vYYYY.MM.DD`, then `.01`, `.02`… the same UTC day.
|
||||
- Every reader (`release_train.py`, `release_channels.py`, the launcher, `horizon-server update`, the website) ranks
|
||||
- Every reader (`release_train.py`, the launcher, `horizon-server update`, the website) ranks
|
||||
every `vX.Y.Z` tag above every dated one.
|
||||
|
||||
### Labels
|
||||
@@ -149,7 +148,7 @@ How releases are numbered, and how installs from before 0.2 reach it: [versionin
|
||||
| `skip-release` | Doesn't trigger a release and isn't listed in the notes |
|
||||
| `run-parity` | Runs the parity job once on a fork's pull request |
|
||||
| `parity-regression` | Opened by the nightly audit for a harness that fails on main |
|
||||
| `release-blocker` | On an issue: holds every beta back from stable while it is open ([Channels](#channels)) |
|
||||
| `release-blocker` | On an issue: no game release is published while it is open ([One channel](#one-channel)) |
|
||||
|
||||
Pull requests without `feature` are listed under **Fixed**. Titles are written for players, since they become
|
||||
the notes.
|
||||
@@ -180,63 +179,38 @@ runs the game: GitHub's runners have neither a GPU worth the name nor the game f
|
||||
- `### Known issues`: the bullets of [docs/known-issues.md](known-issues.md);
|
||||
- thanks to outside contributors, how to install, the disclaimer.
|
||||
|
||||
Kira posts every release in Discord's #releases. An Alpha build (a game pre-release) is posted silently: no ping and
|
||||
Discord's @silent flag, so nobody gets a notification. When the same release becomes Stable it is posted again, and
|
||||
that post pings the releases role when the notes have a `### New` section (at most once every 6 hours). Launcher
|
||||
releases post without a ping.
|
||||
Kira posts every release once in Discord's #releases. It pings the releases role at most once a day: the first game
|
||||
release published after 20:00 UTC, with a short list of what came out since its last ping. Every other post is
|
||||
silent (no ping and Discord's @silent flag). Launcher releases post without a ping.
|
||||
|
||||
### Channels
|
||||
### One channel
|
||||
|
||||
Every game release is published as an **alpha** build, a GitHub pre-release (the workflows, tools and labels
|
||||
call it a *beta*: `release-blocker` holds every beta), so GitHub's *latest* release stays the last
|
||||
**stable** one. The launcher's Settings has an **Updates** choice of two channels (`update_channel` in its
|
||||
`settings.json`, `horizon-launcher update-channel`):
|
||||
Since 2026-10-23 there is one channel. Every game release is published as the release, never a pre-release, and
|
||||
marked GitHub's *latest*: the launcher, `horizon-server update` and `install.sh` take it at once. Because nothing
|
||||
promotes it later, the checks that used to gate a promotion run in the release itself, and the publish job
|
||||
(`tools/release_train.py gate`) publishes nothing unless both pass:
|
||||
|
||||
- **Stable**, the default: a tested build about once a day, the alpha builds promoted below.
|
||||
- **Alpha**: every alpha build as soon as it is built, many times a day; it can break. "Alpha" is the project's
|
||||
word for builds that are still being tested (the whole of Horizon is in beta); Stable is the tested ones. An open
|
||||
launcher looks for releases every 30 minutes on Alpha (4 hours on Stable). Launchers from before 0.2 had a "Beta
|
||||
builds" switch instead; on, it reads as Alpha.
|
||||
- the release smoke test: the macOS build runs the game offscreen on the Mac mini and keeps its report,
|
||||
`smoke-test.json`, only when the game drew a world. The gate reads the report again before publishing, and the
|
||||
release carries it. A run whose macOS build went to GitHub (`MAC_RUNNER=macos-latest`) has no report, so it
|
||||
publishes nothing;
|
||||
- no open issue labelled `release-blocker`. `decide` checks first, so a blocked train builds nothing; the gate checks
|
||||
again right before publishing, so an issue labelled while the builds ran still holds the release. Only the label
|
||||
and the issue's state count, never its text: whoever opened the issue can edit the text after a maintainer
|
||||
labels it. Close the issue (or remove the label) and the next run releases everything waiting, with notes
|
||||
covering all of it.
|
||||
|
||||
`horizon-server update` installs stable builds (`--version <tag>` takes an alpha build by name). In Discord's #releases every
|
||||
Alpha is posted silently and only Stable posts notify (above).
|
||||
A failed gate fails the run; the next run (10 minutes later) decides again. Nothing older than the latest release is
|
||||
ever published: tags only count up.
|
||||
|
||||
`.github/workflows/promote.yml` runs `tools/release_channels.py promote` once a day at 20:00 UTC (21:00 in Paris in
|
||||
winter time, 22:00 in summer), with retries until 21:37 for a run GitHub starts late or skips. It promotes the newest
|
||||
beta that
|
||||
The launcher has no channel setting any more and looks for releases every 30 minutes. The game pre-releases of the
|
||||
old Alpha channel (v0.2.1 on, published before this change) stay listed for anyone who wants one by hand, but no
|
||||
launcher installs them as an update, and `release_train.py` ignores them: the first release of the single channel
|
||||
lists everything since the last release that was not a pre-release (v0.2.0). Launchers from before this change keep
|
||||
updating either way: with Alpha (or 0.17's "Beta builds") on they take every release, pre-release or not; with it
|
||||
off, every release that is not a pre-release, which is now every new one.
|
||||
|
||||
- is newer than the stable release,
|
||||
- had been out 6 hours at 20:00 UTC (published by 14:00 UTC that day; one published later waits for the next day),
|
||||
so every run of the evening picks the same beta and stable moves once a day,
|
||||
- passed its release smoke test: the macOS build attaches `smoke-test.json` (the offscreen game run's report) only
|
||||
when the game drew a world on the Mac mini, so a release built while `MAC_RUNNER` sends macOS to GitHub waits
|
||||
for a hand,
|
||||
- and isn't covered by an issue labelled `release-blocker`. An open blocker holds every beta; closed as completed
|
||||
it still holds the betas published before it closed (they have the bug); closed as not planned it holds
|
||||
nothing. Only the label and the issue's state count, never its text: whoever opened the issue can edit the
|
||||
text after a maintainer labels it, so it can't pick which betas go out.
|
||||
|
||||
Nothing older than the stable release is ever promoted, not even with `force`: GitHub's latest release is what
|
||||
`horizon-server update` and `install.sh` download, so it only moves forward.
|
||||
|
||||
When the oldest beta newer than the stable release has waited 30 hours (it missed a daily promotion it was due for;
|
||||
on a normal day a beta waits at most that long and is promoted), promote.yml opens an issue titled
|
||||
"Promotion to stable has stalled" with the reason from the last check (a blocker left open, smoke tests not
|
||||
running). It closes itself after the next promotion.
|
||||
|
||||
Promoting marks the beta stable and latest and rewrites its notes to list everything since the previous stable
|
||||
release (`release_train.py notes --stable`), so players who skipped the betas see all of it. Older betas stay
|
||||
betas. By hand, from a phone too (GitHub app: Actions, promote, Run workflow):
|
||||
|
||||
```sh
|
||||
gh workflow run promote -f tag=v0.2.3 # that beta now: no wait for 20:00, still no blocker
|
||||
gh workflow run promote -f tag=v0.2.3 -f force=true # even blocked or without a smoke test
|
||||
gh workflow run promote -f dry_run=true # what would be promoted now
|
||||
```
|
||||
|
||||
An alpha build's notes cover only what changed since the release before it (alpha or stable), and say it is an alpha build.
|
||||
`release_train.py decide` counts pull requests from the newest release of either channel, so betas don't
|
||||
release the same changes again.
|
||||
`promote.yml` and `tools/release_channels.py` (the daily promotion at 20:00 UTC) are gone.
|
||||
|
||||
### Signed checksums
|
||||
|
||||
@@ -298,7 +272,8 @@ gh variable set RELEASES_PAUSED --body 1 # no automatic game or launcher rel
|
||||
gh variable delete RELEASES_PAUSED # back on; the next hourly run catches up
|
||||
```
|
||||
|
||||
While paused, runs still decide and say why in their summary; `force=true` still releases.
|
||||
While paused, runs still decide and say why in their summary; `force=true` still releases, but never past an open
|
||||
`release-blocker`.
|
||||
|
||||
### Rolling back
|
||||
|
||||
@@ -308,8 +283,8 @@ A bad release is withdrawn by turning it back into a draft:
|
||||
gh release edit v0.2.3 --draft
|
||||
```
|
||||
|
||||
A beta that is not promoted yet needs no rollback: label an issue about it `release-blocker`. For a stable
|
||||
release: launchers list only published releases, so the previous version becomes the newest one again, launchers that
|
||||
To stop the next releases while a problem is fixed, label an issue about it `release-blocker`. For the bad
|
||||
release itself: launchers list only published releases, so the previous version becomes the newest one again, launchers that
|
||||
didn't install the bad one won't, and players who did can pick the previous version in the launcher's version
|
||||
list (`launcher/src/backend.rs` tests `withdrawn_release_is_never_offered`). The tag stays, so the next release
|
||||
that day takes the next number, and its notes start from the last *published* release, so they list the
|
||||
|
||||
+10
-11
@@ -38,7 +38,7 @@ and some are waiting for Ludovic:
|
||||
| Private vulnerability reporting | **Live** (see the end of this page). |
|
||||
| Signed checksums on releases | **Live** for new releases (#1011): the `release` environment holds the key, and its public half is in `release-keys.txt` (#1023). Releases from before then are unsigned. |
|
||||
| Launchers and servers checking signatures | **Not yet**: #1014 waits as a draft until a signed stable game release and a signed launcher release exist. Until then they trust GitHub's checksum, as before. |
|
||||
| Alpha, then stable | **Live** (#1012): every release is first an alpha build. The launcher's Updates setting picks Stable (the default) or Alpha (the pre-releases). |
|
||||
| Smoke test and release-blocker before publishing | **Live**: since 2026-10-23 every release is the latest at once (one channel, Ludovic's decision), so it is published only after its smoke test passed and while no `release-blocker` is open. The 6-hour beta of the old Alpha, then stable flow (#1012) is gone. |
|
||||
| Reports marked suspicious | **Partly**: the scan of Discord for agents does it. Kira's issues do it once its pull request merges. |
|
||||
| Code owners' review of the pipeline | **Not yet**: `.github/CODEOWNERS` and its protection (#1015) wait for the App, below. Until then pipeline changes merge like any other once `verify` passes. |
|
||||
| Agents on their own GitHub App | **Not yet**: prepared, waiting for Ludovic to create it. Agents still use his account. |
|
||||
@@ -53,11 +53,10 @@ and some are waiting for Ludovic:
|
||||
- **`verify` always runs.** Labels no longer start the checks, and the required `verify` job has no condition, so
|
||||
the only `verify` a change can have is one that ran. Main requires it, from GitHub Actions only, for everyone,
|
||||
admins included.
|
||||
- **Alpha, then stable.** Every release is first an **alpha** build (a GitHub pre-release). It becomes **stable**, the version launchers and
|
||||
servers install by themselves, in the daily promotion (20:00 UTC), only after it has been out 6 hours and passed its
|
||||
smoke test (the game started and drew a world on the Mac mini), and only while no issue labelled `release-blocker`
|
||||
is open. If a beta misses a promotion it was due for, an issue says so. Players who want the newest builds at once
|
||||
pick **Alpha** under Updates in the launcher's Settings. Discord announces stable releases only.
|
||||
- **Checked before it is published.** Every release is published as the latest, which launchers and servers
|
||||
install by themselves, so the release run publishes it only after its smoke test passed (the game started and
|
||||
drew a world on the Mac mini) and only while no issue labelled `release-blocker` is open; otherwise nothing is
|
||||
published.
|
||||
- **Signed updates.** Each release carries a list of its files' checksums, signed with Horizon's release key. The
|
||||
launcher (for the game and for itself) and `horizon-server update` check that signature against the public key
|
||||
built into them, then check the download against the list. Anything unsigned, signed with another key, signed
|
||||
@@ -78,9 +77,8 @@ and some are waiting for Ludovic:
|
||||
## What still needs Ludovic
|
||||
|
||||
- **Approving pipeline changes** (rare): a pull request touching a file in `.github/CODEOWNERS`.
|
||||
- **Holding a release back or speeding one up**, from his phone if he likes. Label an issue `release-blocker` to
|
||||
hold every beta until it is closed. Run the `promote` workflow (GitHub app: Actions,
|
||||
promote, Run workflow) to make a beta stable at once.
|
||||
- **Holding releases back or speeding one up**, from his phone if he likes. Label an issue `release-blocker` to
|
||||
hold every release until it is closed; label a pull request `release-now` to release it as soon as it merges.
|
||||
- **Creating the GitHub App**: one link, "Create GitHub App", then "Install". His login, his clicks.
|
||||
- **Fork pull requests**: their checks run only after a maintainer approves them, and they run on the Mac mini only
|
||||
after a maintainer has read them and added `run-parity`.
|
||||
@@ -90,8 +88,9 @@ and some are waiting for Ludovic:
|
||||
## What this doesn't solve
|
||||
|
||||
- **Code that merges is code that ships.** Signing proves a build came from Horizon's pipeline, not that the code
|
||||
is good. Against a bad change, the safety nets are the checks and harnesses, review, the 6-hour beta and the
|
||||
release-blocker label.
|
||||
is good. Against a bad change, the safety nets are the checks and harnesses, review, the release smoke test and
|
||||
the release-blocker label. Since the single channel there is no 6-hour beta: a change reaches every player
|
||||
within minutes of merging.
|
||||
- **Until agents switch to the App**, they still work with Ludovic's own account, so nothing technical tells his
|
||||
actions from theirs. Code owners' reviews are switched on together with the App.
|
||||
- **The Mac mini** builds the macOS release and also runs pull requests' parity checks: a pull request from this
|
||||
|
||||
+8
-8
@@ -22,10 +22,10 @@ game and the launcher of the 0.2 line.
|
||||
0.2. A `feature` label no longer bumps anything: it only lists the change under **New**.
|
||||
- **Patch releases** are every release the train makes: the patch after the newest release tagged on the line, game
|
||||
and launcher counted separately (the game releases more often, so `v0.2.14` can go with `launcher@0.2.3`).
|
||||
- **Alpha builds** are not separate tags. As before, every game release is published as a GitHub pre-release (an alpha build, what
|
||||
the launcher's Alpha channel installs) under its final tag and promoted in place to stable in the daily
|
||||
promotion at 20:00 UTC, once it has been out 6 hours ([Channels](release-flow.md#channels)). `v0.2.4` is the same
|
||||
build whether it is still a beta or already stable.
|
||||
- **One channel** (since 2026-10-23): every game release is published under its final tag as the release and
|
||||
GitHub's latest, once its smoke test passed and no `release-blocker` is open
|
||||
([One channel](release-flow.md#one-channel)). The game pre-releases from before (v0.2.1 on, the old Alpha
|
||||
channel) keep their tags and stay pre-releases.
|
||||
- **Pre-release tags** (`v0.3.0-rc.1`, `v0.3.0-beta.2`) are semver's and are reserved for a hand-made preview of a
|
||||
new line; the train never makes them. Every reader orders them before their release and after the release
|
||||
before (`v0.2.9` < `v0.3.0-beta.1` < `v0.3.0-rc.1` < `v0.3.0`).
|
||||
@@ -43,7 +43,7 @@ Every 0.2 tag is newer than every tag from before 0.2. Within each:
|
||||
A tag is a 0.2 tag when it is `v` or `launcher@` followed by exactly three numbers (and an optional `-PRE`) with a
|
||||
major below 1000; a date's first number is a year, so `v2026.10.21` never is. The rule is written once per
|
||||
language, with the same tests: `crates/horizon-server/src/update.rs` (`newer`), `launcher/src/backend.rs`
|
||||
(`release_order`), `tools/release_train.py` (`tag_key`, also used by `tools/release_channels.py`) and
|
||||
(`release_order`), `tools/release_train.py` (`tag_key`) and
|
||||
`website/src/versions.js`.
|
||||
|
||||
## The workflows
|
||||
@@ -55,9 +55,6 @@ language, with the same tests: `crates/horizon-server/src/update.rs` (`newer`),
|
||||
- **`launcher.yml`**: `decide --kind launcher` picks `launcher@0.2.N`; the build gets `HORIZON_LAUNCHER_VERSION`
|
||||
(`0.2.N`) and `HORIZON_LAUNCHER_TAG` (`launcher@0.2.N`). The tag tells the launcher which line it is on: a release
|
||||
built with only the version (every launcher before 0.2) is a `launcher-v` one.
|
||||
- **`promote.yml`**: `tools/release_channels.py` promotes the newest due beta, never one older than the stable
|
||||
release; with the shared order, `v0.2.0` follows the last dated stable release and no dated beta can follow
|
||||
`v0.2.0`.
|
||||
- **Notes**: a line's first release (`X.Y.0`) opens with a paragraph saying so; `v0.2.0`'s and `launcher@0.2.0`'s say
|
||||
that releases are numbered from now on, and tell server owners to run `horizon-server update` (or, if their server
|
||||
says it is up to date, `horizon-server update --version v0.2.0`).
|
||||
@@ -98,6 +95,9 @@ the fleet's `release-kick` and the orchestrator's heartbeat prompts.
|
||||
|
||||
## The day Ludovic says go
|
||||
|
||||
Done on 2026-10-22; kept as the record of how 0.2 went out. `promote.yml` and `tools/release_channels.py`, which
|
||||
it uses, are gone since the single channel (2026-10-23, [One channel](release-flow.md#one-channel)).
|
||||
|
||||
Run by the orchestrator, in this order. Until step 3, nothing is published.
|
||||
|
||||
1. Merge, in order: this page, the `horizon-server update` order, the launcher order, the release line (train,
|
||||
|
||||
Reference in New Issue
Block a user