A release framework for local-first Windows desktop applications. Defines what a release is, how it is verified, and what documentation it requires — so that someone who did not build the application can understand what changed, why it changed, and how to verify the artifact they received.
Derived from practices established in FileCabinet. Extended through the Aegis project.
| Area | Summary |
|---|---|
| Versioning | Semantic versioning rules, when to increment, version source of truth |
| Release documents | Required structure, prohibited content, required fields |
| Artifact naming | Deterministic, parseable filename conventions |
| Artifact integrity | SHA-256 (minimum), BLAKE3 (preferred for security-sensitive releases) |
| Build verification | What must be tested and recorded for every release |
| Project manifests | Machine-readable project state and release record |
| Documentation delivery | What ships with the build and why |
| Release checklists | Per-release gates and per-version verification blocks |
| Release blockers | Conditions that block a release regardless of feature completeness |
| Release cadence | Scope-driven, not calendar-driven |
| File | Purpose |
|---|---|
Desktop Application Release Standard.md |
The full release standard. Read this first. |
DesktopApplicationRelease.manifest.schema.toml |
Machine-readable schema defining all required and optional manifest fields. |
Copy each template into your project's docs/ directory, rename it, and fill it in. Templates that apply to every release are marked recurring.
| Template | Purpose | Cadence |
|---|---|---|
templates/ProjectName.manifest.toml |
Concrete project manifest — machine-readable project state and release record | One per project; updated every release |
templates/Release-Note.md |
Release note — what shipped, what it does, the artifact hash | Recurring — every release |
templates/Release-Checklist.md |
Pre-release gate checklist with per-version verification blocks | One per project; appended every release |
templates/Trust-Security-Model.md |
How the application handles sensitive data and who it trusts | Before any security-relevant release |
templates/Dependency-Provenance.md |
Exact versions, sources, and build flags for every external dependency | Before any public release |
templates/Build-Reproducibility-Guide.md |
Clean-clone build steps, required tools, exact versions | Before sharing with other developers |
templates/Threat-Model.md |
Attack surface, trust boundaries, known limitations | Before any security claim |
templates/Integrity-Validation-Matrix.md |
What healthy state looks like; how to detect and repair drift | When a repair or verification workflow exists |
templates/Data-Migration-Contract.md |
Data format migration specification — backup, steps, rollback, failure behavior | Any release that changes persisted data format |
templates/Withdrawn-Release.md |
Withdrawn release record — reason, impact, remediation, post-withdrawal review | When a published release must be retracted |
The release note is the human promise. The manifest is the machine record. The hash binds them.
Not every project needs every document immediately. Use the tier that matches your project's maturity and risk profile.
| Tier | Required When | Documents |
|---|---|---|
| Minimal | Small utility, no sensitive data | README, Manifest, Release Note, Release Checklist |
| Standard | Local-first app with persistent user data | + Build Reproducibility Guide, Dependency Provenance |
| Security-sensitive | Vaults, encryption, credentials, key management | + Trust/Security Model, Threat Model, Integrity Validation Matrix |
| Distribution-grade | Public installers, code signing, auto-update | + SBOM, Withdrawn Release policy, Data Migration Contracts |
Aegis and FileCabinet operate at the Security-sensitive tier. Most tools can start at Minimal and promote as they mature.
drs.ps1 is a PowerShell CLI that makes the standard executable. Run it from any DRS-compliant project directory.
# Typical release workflow
.\path\to\drs.ps1 verify-manifest # check fields before building
# [build installer]
.\path\to\drs.ps1 hash artifacts\installer\*.msi # get SHA-256 for manifest + release note
# [paste hash into manifest and release note]
.\path\to\drs.ps1 check-release # full gate before publishing| Command | What it checks |
|---|---|
drs new <AppName> |
Scaffold project with manifest + checklist |
drs validate |
All required manifest fields present |
drs verify-manifest |
Field consistency (version match, hash format, status) |
drs check-release |
Full gate: manifest + artifact hash + release note + checklist + publish docs |
drs hash <path> |
SHA-256 + file size with copy-pasteable manifest snippet |
drs init-docs |
Copy all doc templates to docs/ with project name applied |
- Copy
templates/ProjectName.manifest.toml→YourAppName.manifest.tomlat your project root - Copy
templates/Release-Checklist.md→docs/YourAppName - Release Checklist.md - Fill in
[project]and[metadata]fields in the manifest - Write your first release note from
templates/Release-Note.md— do this before coding begins
- Update the manifest:
version,[release],[release.installer],[release.verified] - Write or update the release note using the template
- Run through all Pre-Release Gates in the Release Checklist
- Append a Per-Version Verification Block to the checklist
- Confirm the SHA-256 in the release document matches the artifact file on disk
Every installed application must include at minimum:
- The release note for the current version
- The trust/security model document (if the application handles sensitive data)
- The integrity validation matrix (if a repair or verification workflow exists)
Documentation files are text. They add negligible size and are the most durable part of the release artifact.
Ship understanding, not just binaries. A release is not complete until someone who did not build it can understand what changed, why it changed, and how to verify the artifact they received.
Every release has a theme. Name the release before writing code. If the work does not match the name, either the name was wrong or the scope drifted. Catch this before writing the release note.
The artifact hash is the release. Publishing an installer without a SHA-256 hash in the release document is a file drop, not a release.
Detect before mutating. Any system that changes state should make the change visible before it happens. Irreversible actions require explicit operator approval.
Documentation lag is a release blocker. If the release note, manifest, and checklist are not ready, the release is not ready.
examples/MiniVault/ shows what a completed, filled-in DRS document suite looks like for a realistic local-first desktop application. All four required documents are present and cross-consistent:
MiniVault.manifest.toml— complete manifest with all required fieldsdocs/MiniVault v0.1.0.md— finished release note with hash, theme, design boundariesdocs/MiniVault - Release Checklist.md— checklist with completed per-version blockdocs/MiniVault - Trust and Security Model.md— full trust model including crypto primitives, trust boundaries, and known limitations
This standard was derived from practices established in FileCabinet and extended through the Aegis project. See Section 13 of the standard for the full provenance record.