Search is available after the production docs build.

Browse Docs
DocsDevelopersRelease Process

Developers

Release Process

PackOS metadata, SDK validation, launcher packaging, and public release readiness.

Purpose

The release process connects developer outputs to player-ready launcher packages. The goal is to produce files that are installable, repairable, documented, validated, and truthful on the website download page.

The current release path is concrete:

  • Module artifacts are built from ECHO-Modules.
  • SDK templates, schemas, and docs live in ECHO-SDK.
  • Release metadata is published through ECHO-Release-Index.
  • The website mirrors the Release Index snapshot into data/release-index-snapshot.json.
  • ECHO Launcher is the normal player delivery path.

Release Inputs

A release should include:

  • Module builds.
  • META-INF/echo.mod.json.
  • META-INF/echo-addon-package.json for .echo-addon packages.
  • Pack manifest for Ashfall edition packages.
  • Release Index entry.
  • Release channel.
  • Version notes.
  • Dependency list.
  • Checksums or integrity data.
  • Launcher download metadata.
  • Known issues.
  • Troubleshooting path.
  • Docs links for changed systems.

Artifact Families

For module module_id at version version, release generation should produce the exact runtime family needed by the selected edition:

| File | Consumer | | --- | --- | | module_id-version.echo-addon | Ashfall Native Edition | | module_id-version-neoforge.jar | Ashfall NeoForge Edition | | module_id-version-standalone.jar | Ashfall Standalone Edition | | module_id-version-sources.jar | Developers, traceability, debugging |

Every runtime artifact should carry META-INF/echo.mod.json. Native packages should also carry echo-addon-package.json.

Release Index Entry

Release Index entries use the SDK schema release-index-entry.schema.json and include identity, source, artifacts, compatibility, trust, and validation fields:

{
  "id": "hello_content_addon",
  "kind": "addon",
  "version": "0.1.0",
  "channel": "alpha",
  "publisher": "knoxhack",
  "sourceRepo": "knoxhack/ECHO-SDK",
  "releaseTag": "v0.1.0-sdk-alpha",
  "commitSha": "abcdef0",
  "artifacts": {
    "native": "hello_content_addon-0.1.0.echo-addon",
    "neoforge": "hello_content_addon-0.1.0-neoforge.jar",
    "standalone": "hello_content_addon-0.1.0-standalone.jar",
    "sources": "hello_content_addon-0.1.0-sources.jar"
  },
  "dependencies": [],
  "compatibility": ["echo_native", "neoforge", "echo_runtime_standalone"],
  "trust": "official",
  "validation": "echoValidate"
}

Use real asset names and real SHA-256 values in release data. Do not publish placeholder checksums, empty checksums, or generic artifact names.

Pack Manifest

Ashfall edition packages use echo.pack.v1 pack metadata:

{
  "schemaVersion": "echo.pack.v1",
  "id": "ashfall-neoforge-edition",
  "version": "0.1.0",
  "target": "neoforge",
  "runtime": {
    "id": "minecraft-neoforge",
    "version": "1.21.1"
  },
  "requiredArtifacts": [
    {
      "id": "echoterminal",
      "kind": "module",
      "version": "1.0.0"
    }
  ]
}

The selected target controls which module artifact family the launcher resolves.

Validation Gates

Run SDK and website validation before release:

python tools/echo_sdk.py validate templates --json
python tools/validate_echo_contracts.py --json
npm run audit:site

For Gradle addon projects, run:

./gradlew echoValidate
./gradlew echoBuildReleaseBundle
./gradlew echoVerifyNativeLiveProof

Useful release gates include:

  • Required metadata exists.
  • Dependencies resolve.
  • Versions are compatible.
  • Runtime target is clear.
  • Artifact names match target families.
  • Checksums exist for downloadable artifacts.
  • Launcher assets exist when direct installer buttons are shown.
  • Docs links are not broken.
  • Release notes are present.
  • Known issues are written for players and testers.
  • Native live-client proof exists before claiming Native lane readiness.

Player Readiness

Before a release is public, ask:

  • Can a player install it through ECHO Launcher?
  • Can the launcher repair it?
  • Is the runtime target clear?
  • Is there a known troubleshooting path?
  • Are the release notes understandable?
  • Are manual assets clearly marked as advanced?
  • Do docs explain the changed systems?

Players should not need to understand module jars, manifests, or lockfiles just to play. Advanced assets can exist, but the primary path should stay launcher-first.

Developer Readiness

Before a release is promoted, ask:

  • Did every changed module update release notes?
  • Did dependencies change?
  • Did any save data require migration?
  • Did packet or action IDs change?
  • Did UI provider IDs change?
  • Did PackOS metadata describe the new state?
  • Did docs links still resolve?
  • Did generated website data stay in sync with sibling repos?

This connects release work to Module Template, Data Storage, and Networking.

Website Snapshot

The website reads the local Release Index checkout during npm run sync:ecosystem and writes:

  • data/release-index-snapshot.json
  • data/products.json
  • data/modules.json
  • data/sdk-docs-manifest.json
  • generated /docs/sdk pages

Run npm run audit:site after sync. The drift audit fails when mirrored SDK docs are stale, product routes are broken, modules do not match ECHO-Modules, or release snapshot data loses required coverage.

Common Mistakes

  • Publishing files without a clear player path.
  • Treating advanced assets as normal install instructions.
  • Forgetting known issues because the build passed.
  • Shipping module changes without docs or release notes.
  • Marking a runtime lane player-ready before its artifacts and proof exist.
  • Leaving placeholder checksums, fake artifact names, or generic values in public release metadata.

Related Docs

Next Step

Write release notes before publishing. Then verify the download portal, launcher setup docs, Release Index snapshot, and troubleshooting docs all describe the same player path.