Release (Hugging Face)

---
name: release
description: Release workflow for deploying OpenEnv environments to Hugging Face Spaces and keeping canonical references in sync.
metadata:
  origin: Hugging Face
---

# Release Skill

This skill orchestrates the repo-embedded deployment tooling and documents the `openenv`-namespace canonicalization process.

## Prerequisites
- `hf` CLI authenticated (run `hf auth login` or set `HF_TOKEN`).
- Local build dependencies installed so `scripts/prepare_hf_deployment.sh` can stage Docker contexts.
- Access to `scripts/manage_hf_collection.py` for collection updates and discovery.

## Primary Flow
1. **Stage envs with `scripts/prepare_hf_deployment.sh`.** Default arguments deploy every *deployable* env from `envs/`. Pass `--env <name>` to target a subset. The script:
   - Resolves the requested OpenEnv ref for staged dependency rewrites. If `0.2.2` is only a release-candidate label and no `v0.2.2` tag exists yet, the script should fall back to `main` for env dependency rewrites while keeping the Hub suffix at `-0.2.2`.
   - Rewrites loose `openenv-core[core]>=...` specs and direct Dockerfile installs to `git+https://github.com/huggingface/OpenEnv.git@<resolved-ref>` so the sweep does not silently install `0.2.1` from PyPI.
   - Builds a staging tree with `src/`, `envs/<env>/`, and a rewritten `Dockerfile` that sets `BASE_IMAGE` to `ghcr.io/huggingface/openenv-base:latest` unless a hash is supplied.
   - Generates a README with Hub metadata, enforces `openenv`/`openenv-<version>` tags, and adds the `HUB_TAG` used in collection sync.
   - Uses `hf repo create`/`hf upload` plus visibility flags to push Docker spaces.
2. **Suffix naming and privacy.** Deploy to private spaces named `<env>-0.2.2` (set `SPACE_SUFFIX=-0.2.2` or rely on the version-derived default). Use `--private` to keep the collection private for now. The repo deploy script should update only the versioned collection during this phase, not the global tagged collection.
3. **Runtime verification.** For private Spaces, verify through authenticated `hf.space` domains, not anonymous browser URLs. Use `scripts/verify_private_spaces.py --hf-namespace openenv --suffix -0.2.2` or inspect `hf spaces info <space>` plus the runtime domain from `runtime.raw.domains`. Prefer `hf spaces ls --expand=runtime` to confirm `RUNNING`/`SLEEPING`. For stuck or error states, consult `scripts/prepare_hf_deployment.sh` logic or fall back to the `hf-space-recovery` skill.
   - Do not treat `/health` alone as sufficient. This sweep found false positives where `/health` was `200` but runtime use still failed: `chat_env-0.2.2` returned `500` on `/reset`, and `tbench2_env-0.2.2` also returned `500` on `/reset`.
   - For HTTP envs, an authenticated `POST /reset` is the minimum usability gate. If the action schema is simple, follow with a schema-correct `POST /step` probe as well; `snake_env`, `finrl_env`, and `sumo_rl_env` all surfaced step-time failures that a health-only check would miss.
   - Some envs are slow enough that `POST /reset` may time out on a 20-second probe (`git_env`, `unity_env`). Treat those as inconclusive until manually retried with a longer timeout or an env-specific probe.
   - Certain canonical spaces such as `openenv/echo_env` and the TextArena variants expose multiple `READY` runtime domains. The verifier now probes every `READY` domain and reports success once any domain returns usable data, so the canonical status is based on the first passing domain rather than the first listed domain.

## Canonical update decision
- Canonical environments (no suffix) should point to `main` only when the private `-0.2.2` candidate builds and passes health checks.
- If a suffixed space fails to start or its Docker build is broken, leave the canonical reference untouched and pin that env’s `pyproject.toml` dependency to `<0.2.2` to prevent inadvertent upgrades.
- When a suffixed space succeeds, add it to the private versioned collection with `scripts/manage_hf_collection.py --version 0.2.2 --collection-namespace openenv --skip-global-collection --space-id <space>`.
- Existing unsuffixed canonicals are only a subset of `envs/`. Before promotion, map repo envs to actual canonical repos on the Hub:
  - direct matches: `atari_env`, `browsergym_env`, `chat_env`, `coding_env`, `echo_env`, `openspiel_env`, `sumo_rl_env`
  - repo-name mismatches: `repl_env -> openenv/repl`, `tbench2_env -> openenv/tbench2`
  - textarena aliases: `textarena_env` promotes into productized canonicals such as `openenv/sudoku` and `openenv/wordle`, not `openenv/textarena_env`
  - do not infer repo names from the env directory when the namespace already has a canonical alias; list the current `openenv` spaces first and promote into the existing repo when one exists
  - Observed canonical spaces in `openenv` as of this sweep include `openenv/atari_env`, `openenv/browsergym_env`, `openenv/chat_env`, `openenv/coding_env`, `openenv/echo_env`, `openenv/finqa_env`, `openenv/openspiel_env`, `openenv/repl`, `openenv/sudoku`, `openenv/wordle`, `openenv/sumo_rl_env`, and `openenv/tbench2`; keep this list current when planning canonical promotions.

## Collection handling
- Run `scripts/manage_hf_collection.py` with a single release tuple (namespace `openenv`, version `0.2.2`, suffix `-0.2.2`).
- Default behavior adds discovered tagged spaces to the versioned collection, creating or reusing the slug `OpenEnv Environment Hub <version>`.
- Supply `--space-id` explicitly for each successfully redeployed suffixed space to avoid relying on discovery heuristics and to document the tested set.
- For canonical updates, handle repo-name mismatches explicitly. `repl_env` maps to `openenv/repl`, `tbench2_env` maps to `openenv/tbench2`, and `textarena_env` may be represented by productized aliases such as `openenv/sudoku` or `openenv/wordle` rather than an env-dir-matching Space.

## Toolchain reminders
- Always run the release script from the repo root so relative paths to `envs/`, `src/`, and `pyproject.toml` resolve.
- Keep `uv sync` detached at the start of Docker builds: the helper script injects `uv install`/`uv sync` edits automatically.
- `scripts/prepare_hf_deployment.sh --skip-collection` can be used when only validating builds without touching collections.
- For private-space verification, anonymous `https://<space>.hf.space/...` requests return a generic 404. Use an authenticated header from the locally logged-in `hf` token or `scripts/verify_private_spaces.py`.
- Canonical spaces may expose multiple `READY` domains. Do not stop at the first one. In this sweep, `openenv/echo_env` advertised both `openenv-echo-env-v2.hf.space` and `openenv-echo-env.hf.space`, and `openenv/sudoku` advertised both `openenv-textarena.hf.space` and `openenv-sudoku.hf.space`; the first domain in each pair returned 404 while the second served the env correctly. Probe every `READY` domain until one passes.
- If a suffixed repo already contains the intended Dockerfile/source fix but HF still shows an old `BUILD_ERROR`, use `HfApi().restart_space(..., factory_reboot=True)` to force a fresh rebuild of the same commit.
- When `scripts/prepare_hf_deployment.sh` stages legacy Dockerfiles that `COPY src/core/`, it now injects `COPY src/openenv/ /app/src/openenv/` and limits `PYTHONPATH` to `/app/src` because exposing `/app/src/core` earlier shadowed the stdlib `types` module and triggered `ImportError: cannot import name 'GenericAlias'`.

## Env-Specific Fix Patterns
- `browsergym_env`: avoid live Hub-time `git clone` of MiniWoB++ when possible. A pinned tarball snapshot is more reproducible than cloning the repo during every Space build.
- `websearch_env`: staged `openenv-core` rewrites can become `git+https://...` dependencies, so the builder image must have `git` available before `uv sync`.
- `maze_env` and `snake_env`: when a Dockerfile stages the repo root under `/app/env`, add `/app/env/src/core:/app/env/src:/app/env` to `PYTHONPATH` so the Space can use the checked-out repo sources and compatibility shims during validation.
- Legacy Dockerfiles that add `/app/src/core` directly to `PYTHONPATH` can shadow the Python stdlib with `/app/src/core/types.py`, causing startup failures like `ImportError: cannot import name 'GenericAlias' from partially initialized module 'types'`. Stage `src/openenv/` into `/app/src/openenv/` and put only `/app/src` on `PYTHONPATH`.

## Post-release cleanup
- Record which envs passed vs. failed. Failed envs should stay pinned below `0.2.2` until a fix is committed.
- Archive or delete test suffix spaces once their artifacts are promoted to canonical releases to reduce clutter in the `openenv` namespace.
- Capture `hf spaces info`/`curl .../health` output for the final success set so the release briefing notes the exact runtime status used to flip canonical references.