docs: distinguish deployments from versions in terminology - #982
Conversation
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
![miren-code-agent[bot]](https://avatars.githubusercontent.com/u/174767976?s=60&v=4){kind=small}
There was a problem hiding this comment.
🍪 biscuit: ✅ ready to merge — auto-review, non-blocking
This is a focused, well-reasoned docs clarification. The old "Deployment" entry in terminology.md conflated the act of deploying with the artifact it produces, which was genuinely confusing — the new text separates them cleanly: a deployment is the action, a version is the artifact, and a failed deployment produces no version. The new "Rollback" entry fills a real gap, and the cross-links between all three entries ([deployment](#deployment), [version](#version), [rollback](#rollback)) are all valid anchors.
The parallel update to deployment.md line 21 is consistent: the old sentence implied every deployment creates a version ID; the new sentence correctly distinguishes successful from failed deployments.
One small pre-existing tension worth flagging (not introduced by this PR): the miren app history example table in deployment.md shows a VERSION column with an ID-formatted string even for the ✗ (failed) row. Under the new terminology a failed deployment has no version, so that column label is a little misleading for failed rows. Since this PR didn't introduce that table and its meaning is pre-existing, it's not a blocker here — but it'd be worth a follow-up to either relabel that column "DEPLOYMENT ID" or add a note that the ID shown for failed rows is the deployment ID, not a version ID.
Ready to merge as-is.
🍪 full review note · comment /biscuit review to run biscuit again.
Inline comments
docs/docs/deployment.md:122
Under the new terminology, a failed deployment produces no version — but the VERSION column header here applies to all rows, including the ✗ (failed) one (line 148 shows myapp-vCVmuoeQCzjoNN9hGsu14c with a ✗ status). A reader who just read the new Deployment/Version definitions will wonder what that column means for a failed row. Worth a small follow-up to relabel it DEPLOYMENT or ID, or add a note that for failed deployments this is the deployment record ID rather than a version ID. (Pre-existing issue, not introduced by this PR — just surfaces more sharply now.)
📝 WalkthroughWalkthroughUpdated deployment documentation to distinguish deployment objects and attempts from resulting versions. Successful deployments create versions, while failed attempts remain in history without producing versions. Added a rollback glossary entry describing re-release of an existing version without rebuilding, and linked the version definition to rollback behavior. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/docs/deployment.md`:
- Line 21: Update the deployment description in docs/docs/deployment.md at line
21 to qualify version creation as applying to successful build deployments and
state that rollbacks re-release an existing version without creating a new one.
Update docs/docs/terminology.md at line 151 to replace the generalized
successful-deployment statement with wording that explicitly excludes rollbacks.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 2ae71ece-1974-47d2-a740-2f4b9a50a9fb
📒 Files selected for processing (2)
docs/docs/deployment.mddocs/docs/terminology.md
2 participants
Summary
Clarifies the terminology docs to stop conflating a deployment with the version it produces, per the design review with Paul.
A deployment is an attempt to build and release a version — a distinct object with its own ID. A successful deployment produces a version; a failed one produces no version but stays in history as a record of the attempt. A rollback is a deployment that re-releases an existing version without building.
Changes
terminology.md— Deployment: rewritten. Was defined as "a specific version of your app that has been built and deployed," which conflated the action with the artifact. Now describes the attempt/artifact split and the success/failure outcomes.terminology.md— Rollback: new term — a type of deployment that re-releases an existing version and skips the build.terminology.md— Version: only successful deployments create a version; added a cross-link to Rollback.deployment.md: fixed one line that treated the deployment ID and version ID as the same thing.Context
From the Jul 27 design review — deployment and version are two different objects (
miren deploystarts a deployment, which then works to build a version). This is the "Update Deployment PR" / "Fix Terminology Page" follow-up from that meeting.