fix(release): fast self-contained idempotent pipeline + release runbook (#17)

* fix(release): fast self-contained idempotent pipeline + release runbook

v0.11.0 was released from the web UI when the tag was pushed, so the
workflow's unconditional gh release create failed on the collision and no
assets were ever attached. Rework the pipeline around that failure mode and
around wall-clock:

- no marketplace actions: plain git checkout, pinned rustup install
  (bootstrapped on the rust-less macOS images), gh for all release IO
- the reproducible-build gate runs as two parallel jobs per target instead
  of two serial builds in one job (~halves wall-clock; now also cross-runner
  instead of same-machine); windows-x64 stays single-build
- release creation is a race-safe guard in each leg (notes from
  .github/release-notes.md); all uploads --clobber so re-runs converge
- one publish job verifies the published assets against both build attempts,
  aggregates SHA256SUMS.txt, and runs the npm publish from the same download
- DEVELOPMENT.md gains the release runbook

* chore: release 0.11.2

Author: eordano

.github/release-notes.md

@@ -0,0 +1 @@
+Reproducible builds: the linux and macOS binaries were each built from a clean tree in two independent CI jobs (separate runners) and required bit-identical before publishing; the windows binary is built once (mingw's linker has a residual link-order non-determinism). Toolchain: rust 1.97.0 (pinned), `--locked` against the committed Cargo.lock, `SOURCE_DATE_EPOCH` from the tagged commit. Each archive is self-contained: the `abgen` server binary plus the `template/` and `shader/` assets it needs, resolved from the binary's own directory (`ABGEN_ROOT`/`ABGEN_SHADER_BUNDLE` override). Runtime requirements - Linux (x64 and arm64): glibc >= 2.35 and libstdc++6/libgcc_s (present on any mainstream distro). Windows x64: none, the mingw runtime DLLs ship in the archive next to the exe. Windows arm64: none, a single static exe (llvm-mingw/libc++). macOS (Apple Silicon and Intel): system libraries only. Optional everywhere: libturbojpeg (bit-parity JPEG decode with the upstream ab-cdn pipeline; without it JPEG textures decode through a pure-Rust fallback - valid output, not guaranteed byte-identical to upstream bundles). The same binaries publish to npm as `@dcl/abgen` (per-platform packages as optionalDependencies; `npx @dcl/abgen` runs the server).

.github/workflows/release.yml

@@ -180,3 +180,27 @@ AGPL-3.0-or-later (the Rust crate) - full text in [LICENSE](LICENSE). Vendored t
 Zlib, draco_decoder = MIT/Apache-2.0, libjpeg9c = IJG. Shader/template bundles are generated
 Decentraland content artifacts (sha256-pinned; regenerable via `scripts/bootstrap-runtime.sh`). Note:
 the lib sets `#[global_allocator] mimalloc`; any downstream embedding the lib inherits it.
+
+## Releasing
+
+The release pipeline (`.github/workflows/release.yml`) is plain shell on GitHub-hosted
+runners - no third-party or marketplace actions. Beyond the repo it trusts only rustup.rs
+(version-pinned toolchain) and the sha256-pinned llvm-mingw tarball. Every release
+operation is idempotent, so job re-runs converge on the full asset set.
+
+1. Land a `chore: release X.Y.Z` PR bumping the crate version (Cargo.toml + Cargo.lock).
+2. Tag the merge commit and push the tag:
+   `git tag vX.Y.Z <merge-sha> && git push origin vX.Y.Z`
+   Don't pre-create the release in the web UI: the pipeline adopts an existing release
+   (that is how v0.11.0 first shipped assetless), but only a CI-created one carries the
+   notes from `.github/release-notes.md`.
+3. What runs: every target builds twice in parallel jobs on separate runners
+   (windows-x64 once - mingw ld is non-deterministic); each leg packages, smoke-tests
+   (`--version` + `/readyz`), and uploads its archive with `--clobber`. The `publish` job
+   re-downloads the published assets, requires bit-identical hashes from both build
+   attempts, verifies contents, uploads the aggregated `SHA256SUMS.txt`, and publishes
+   npm (skipped explicitly when `NPM_TOKEN` is unset - why `@dcl/abgen` is not on npm).
+4. Verify: exactly 7 assets on the release page (6 archives + `SHA256SUMS.txt`).
+5. Failed leg: re-run failed jobs from the Actions UI; everything converges.
+
+`workflow_dispatch` on a branch is a build+smoke dry run (no release, no uploads).

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "abgen"
-version = "0.11.1"
+version = "0.11.2"
 edition = "2021"
 description = "Decentraland asset-bundle converter + ab-cdn-compatible JIT server — clean-room reimplementation of asset-bundle-converter."
 license = "AGPL-3.0-or-later"

DEVELOPMENT.md

@@ -1,6 +1,6 @@
 [package]
 name = "dcl-contents"
-version = "0.11.1"
+version = "0.11.2"
 edition = "2021"
 description = "Content-DB active-entity component, asset-bundle status DTOs, manifest-status reader, and the unsigned registry HTTP surface (profiles, entity status, world manifests)."
 

crate/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "abgen-gpu-kernel-ptx"
-version = "0.11.1"
+version = "0.11.2"
 edition = "2021"
 license = "AGPL-3.0-or-later"
 description = "rustc-native nvptx64 PTX kernels for abgen-gpu-core (nightly + -Z build-std=core; artifact consumed by host via ABGEN_GPU_PTX)"

crate/dcl-contents/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "abgen-wasm-poc"
-version = "0.11.1"
+version = "0.11.2"
 edition = "2021"
 publish = false