From 33cd0948be8d89412347ae3c24eac62d12316984 Mon Sep 17 00:00:00 2001 From: Mary Cutrali Date: Mon, 27 Jul 2026 13:20:34 -0500 Subject: [PATCH] docs: distinguish deployments from versions in terminology MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A deployment is an attempt to build and release a version — a distinct object with its own ID that succeeds into a version or fails as a record. The previous definition conflated a deployment with the version it produces. - Rewrite the Deployment definition to describe the attempt/artifact split - Add a Rollback term (a deployment that re-releases a version without building) - Note that only successful deployments create versions - Fix the same conflation in deployment.md --- docs/docs/deployment.md | 2 +- docs/docs/terminology.md | 10 ++++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/docs/deployment.md b/docs/docs/deployment.md index 2316f494..b4a34b94 100644 --- a/docs/docs/deployment.md +++ b/docs/docs/deployment.md @@ -18,7 +18,7 @@ When you run `miren deploy`, Miren: 2. **Detects and builds on the server** — the server inspects your source code to detect the [language, framework](/guides), and [services](/services), then builds a container image using the detected stack (or your Dockerfile) 3. **Activates the new version** — rolls out the new version, replacing the previous one -Every deployment is tracked with a unique version ID, its current status, and the git commit it came from. You can inspect, roll back, or redeploy any previous version at any time. +Each deployment is a tracked object with its own ID, a status, and the git commit it came from. A successful deployment produces a new version (identified by a version ID); a failed one produces no version but stays in history as a record of the attempt. You can inspect, roll back, or redeploy any previous version at any time. ## Deploying from a Project Directory diff --git a/docs/docs/terminology.md b/docs/docs/terminology.md index 97924bd3..ff99885e 100644 --- a/docs/docs/terminology.md +++ b/docs/docs/terminology.md @@ -50,7 +50,9 @@ The [route](#route) automatically assigned to an app when it is first deployed. ## Deployment -A specific version of your app that has been built and deployed. Each deployment creates a new container image and can be rolled back if needed. +An attempt to build and release a specific [version](#version) of your app. Running `miren deploy` starts a deployment, which gets its own ID. A successful deployment produces a new [version](#version); a failed deployment produces no version but remains as a record of what was attempted and why it failed. A [rollback](#rollback) is a deployment that re-releases an existing version without building a new one. + +A deployment and the version it produces are distinct objects: the deployment is the action, and the version is the resulting artifact. ## Disk @@ -112,6 +114,10 @@ A simple file format for defining [services](#service) in your app. Each line ma Maps a hostname to an application. Routes determine how HTTP traffic reaches your apps. Your first app gets a [default route](#default-route) automatically. See [Traffic Routing](/traffic-routing). +## Rollback + +A type of [deployment](#deployment) that re-releases a previously built [version](#version) instead of building a new one. Because the container image already exists, a rollback skips the [build](#build) step and re-releases the target version as-is. + ## Route Protection Authentication at the routing layer using an [identity provider](#identity-provider). Unauthenticated requests are redirected to an OIDC provider for login. After authentication, JWT claims are injected as HTTP headers (e.g., `X-User-Email`) before the request reaches your app — no in-app auth code required. See [Protecting Routes](/route-protect). @@ -142,7 +148,7 @@ Time to live — the expiration timer for an [ephemeral version](#ephemeral-vers ## Version -A unique identifier for a specific build of your app (e.g., `myapp-vCVkjR6u7744AsMebwMjGU`). Each [deployment](#deployment) creates a new version, which tracks the container image, git commit, and configuration. Previous versions can be rolled back to without rebuilding. +A unique identifier for a specific build of your app (e.g., `myapp-vCVkjR6u7744AsMebwMjGU`). Each successful [deployment](#deployment) creates a new version, which tracks the container image, git commit, and configuration. Previous versions can be rolled back to without rebuilding — see [rollback](#rollback). ## WAF