Releasing

Cutting a release, how packages relate to releases, and the branch and profile conventions around them.

The notes for shipped releases stay in their own file, RELEASE_NOTES.md, because the release workflow feeds that file to GitHub verbatim.

Release process

Dezh uses review releases rather than production releases at this stage.

Release Goals

A review release should give an external reviewer:

• a fixed source revision
• repeatable CI evidence
• bootable QEMU kernel artifacts
• a review demo transcript
• SDK .dzp sample packages
• checksums and an artifact manifest
• a review environment they can build locally from Dockerfile.review

Version Names

Use tags in this shape:

v0.1-review
v0.2-review

The suffix makes the release status explicit. These are not production OS releases.

Before Tagging

Run:

python tools/review/run_full_review.py --full

The full review suite validates:

• public hygiene
• host workspace tests
• RISC-V kernel build
• x86_64 kernel build
• RISC-V QEMU smoke
• x86_64 QEMU smoke
• review demo transcript
• SDK package lifecycle acceptance
• release artifact generation

Create A Release

From main, after it has fast-forwarded from develop:

git tag -a v0.1-review -m "Dezh OS v0.1-review"
git push origin v0.1-review

Pushing the tag starts .github/workflows/release.yml.

Release Artifacts

The release workflow attaches:

• dezh-<tag>-riscv64-qemu-kernel.elf
• dezh-<tag>-x86_64-qemu-kernel.elf
• transcripts/riscv64.md
• dezh-<tag>-hello.dzp
• dezh-<tag>-review-docs.zip
• release-manifest.json
• SHA256SUMS

Container Package

The release workflow publishes no container image. It used to try; see the review environment for what happened and how to build it locally from Dockerfile.review, which carries Rust, Python, QEMU and the Rust targets review needs.

Release Discipline

• Do not tag from a dirty tree.
• Do not create a release without passing the full review suite.
• Do not attach local disk images or ad-hoc binaries.
• Do not publish production claims in review release notes.
• Do not use GitHub Packages for app storage semantics; Dezh packages are .dzp artifacts and OS-managed package-store entries.

Packages and releases

GitHub shows two related surfaces: Releases and Packages. Dezh uses both, but for different purposes.

Releases

Releases are the public review checkpoints.

Each release should contain:

• QEMU kernel artifacts
• a generated review transcript
• a sample SDK .dzp package
• documentation archive
• artifact manifest
• checksums

This lets a reviewer inspect a fixed point in the project without guessing which commit, transcript, or binary was used.

The review environment

Build it locally:

docker build -f Dockerfile.review -t dezh-review-env .

The image is not the OS. It is the build-and-review environment: Rust targets, Python, and QEMU.

The release publishes it to GHCR, and it is public:

docker pull ghcr.io/alisalimi77/dezh-review-env:latest

The record of getting this wrong is kept below, because this page told reviewers the opposite for two releases and it was checkable in one command.

The publish was refused on v0.3-review and v0.4-review with denied: permission_denied: write_package, and after the second refusal the steps were removed rather than left turning the release red — a gate that breaks for reasons unrelated to the change under review is one people learn to ignore, and this one would have taught that to the reviewers the project is asking for critique from.

What was written here at the same time was wrong, and wrong in the direction that flatters nobody: "There is no published image", "no tag of the image has ever existed", "docker pull was never going to work". All three were false when written. v0.1-review, v0.2-review and latest were in the registry the whole time and anonymously pullable; a docker pull would have said so. README repeated the claim.

The timeline nobody looked at:

The first denial and the day the repository went public are the same day. What broke was the package's own Actions access — web-UI state, not anything in this repository — which is why packages: write in the workflow and a write default workflow-token permission both checked out and neither helped.

Two other explanations were written down before that one. The first was a visibility problem, which was never it. The second was that the push was refused because the package did not exist yet — also wrong, and it is the assumption that made the false claim above feel safe: nobody pulls an image they have concluded cannot exist.

Granting this repository write on the package fixed it. It was confirmed before restoring anything, by a probe using GITHUB_TOKEN — the credential that was refused, since a personal access token would have succeeded and proved nothing — opening a blob upload session against the package: HTTP 202, and no tag left behind.

Dezh .dzp Packages

Dezh application packages are .dzp artifacts. They are installed into the OS through the console and the service-mediated package store.

They are intentionally separate from GitHub Packages:

• GitHub Packages distributes host-side review tooling.
• .dzp packages exercise Dezh's own app installation model.
• OS package state remains capability-scoped, transactional, and auditable.

Why Not Publish Every App To GitHub Packages?

The package-store design is part of the OS thesis. Treating every Dezh app as a generic host package would hide the lifecycle that Dezh is trying to make explicit: capability requests, install journal, registry state, rollback, quarantine, and garbage collection.

For public review, release assets are enough. Later, Dezh can add a dedicated package index with signatures, reproducible builds, and capability review.

Git workflow

Dezh uses a two-branch integration flow:

• develop is the active integration branch.
• main is the stable branch for coherent, tested milestones.

Feature Work

Create focused branches from develop:

git switch develop
git pull
git switch -c feature/<short-name>

Use these prefixes:

• feature/<name> for product or kernel functionality.
• fix/<name> for bug fixes.
• docs/<name> for documentation-only work.
• spike/<name> for exploratory work.

Required Validation

Before merging to develop:

cargo test --locked --workspace
cd dezh-boot && cargo build --locked && cd ..
cd dezh-boot-x86 && cargo build --locked && cd ..

For bare-metal changes, also run:

python tools/ci/qemu_smoke.py riscv64 \
  --kernel dezh-boot/target/riscv64gc-unknown-none-elf/debug/dezh-boot \
  --qemu qemu-system-riscv64

python tools/ci/qemu_smoke.py x86_64 \
  --kernel dezh-boot-x86/target/x86_64-unknown-none/debug/dezh-boot-x86 \
  --qemu qemu-system-x86_64

For external-review states, also run:

python tools/demo/run_review_demo.py --qemu-riscv qemu-system-riscv64
python tools/review/scan_public.py

External Review Snapshot

External review material should be exported from a clean snapshot, not from a branch with internal work-in-progress history. Use the review package tool:

python tools/review/make_review_package.py

The exported package should pass the public hygiene scan before distribution.

Main Branch

Fast-forward main only after the milestone is coherent and the validation commands above are green.

GitHub profile

Use this text for the public GitHub repository profile.

Description

Intent-native, capability-secure OS research prototype with user-space drivers, typed IPC, transactional package lifecycle, and reboot-safe QEMU demos.

Shorter variant:

Capability-secure OS research prototype with user-space drivers, typed IPC, and transactional package lifecycle.

Suggested Topics

• operating-system
• research-os
• capability-security
• microkernel
• riscv
• qemu
• user-space-drivers
• typed-ipc
• package-management
• rust
• systems-programming
• sandboxing
• agent-sandbox
• ai-agents
• rollback

Website

Leave empty for now unless a dedicated documentation site is published.

Social Preview

Recommended preview concept:

• dark technical diagram background
• title: Dezh OS
• subtitle: Intent-native. Capability-secure. Effect-accountable.
• small visual motif: kernel boundary, U-mode services, package lifecycle

Do not use screenshots that expose local paths, private terminals, or development-only artifacts.