doc: document version upgrades

[NathanFlurry]

No description provided.

[railway-app]

🚅 Deployed to the rivet-pr-3901 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-cloud	😴 Sleeping (View Logs)	Web	Jan 15, 2026 at 3:34 am
frontend-inspector	😴 Sleeping (View Logs)	Web	Jan 15, 2026 at 3:33 am
website	❌ Build Failed (View Logs)	Web	Jan 15, 2026 at 3:23 am

[NathanFlurry]

• fix(website): fix code group #3914
• doc: auto-generate docs for engine config and registry config #3902
• doc: document version upgrades #3901 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: Document Version Upgrades

Overview

This PR adds documentation for Rivet Actor version management and upgrade behavior. The documentation is well-structured and informative.

---

✅ Strengths

1. Clear Structure: The documentation flows logically from concept to configuration
2. Visual Aids: Good use of Mermaid diagrams to illustrate version upgrade scenarios
3. Practical Examples: Both environment variable and programmatic configuration examples provided
4. Helpful Recommendations: Suggestions for version numbering strategies (git commit count, CI build number) are practical

---

📝 Issues Found

1. Incomplete Sentence (Line 41)

Severity: Medium

Old actors continue running on the old version until.

This sentence is incomplete. It should clarify what happens to the old actors. Suggested fix:

Old actors continue running on the old version until they sleep from inactivity.

2. Inconsistent Indentation in Mermaid Diagrams

Severity: Low

Lines 32 and 50 use tabs instead of spaces for indentation in the Mermaid diagrams:

-	R2->>R1: Drain old actors
+    R2->>R1: Drain old actors

-	Note over R1: Actor 1 sleeps from inactivity
-	Note over R2: Actor 1 wakes up when prompted
+    Note over R1: Actor 1 sleeps from inactivity
+    Note over R2: Actor 1 wakes up when prompted

While Mermaid may render correctly, consistent spacing improves maintainability.

3. Typo: "built time" (Line 81)

Severity: Low

We recommend injecting a value at built time

Should be:

We recommend injecting a value at build time

4. Mermaid Diagram Accuracy

Severity: Low

In the "Drain Disabled" scenario, the diagram shows "Actor 1" sleeping and waking up, but it doesn't clearly show that when Actor 1 wakes up, it's being recreated on the new version. Consider adding a note to clarify:

sequenceDiagram
    participant R1 as Runner v1
    participant R2 as Runner v2

    Note over R1: Currently running
    Note over R2: Deployed
    Note over R1: Actor 1 sleeps from inactivity
    Note over R2: Actor 1 wakes up on new version

Loading

---

🔍 Other Observations

1. Good Integration: The rehype.ts change properly integrates Mermaid support with dark theme configuration
2. Navigation: Sitemap update correctly places the new doc in the actors section
3. No Security Concerns: Documentation-only changes with no security implications
4. No Performance Impact: Static documentation changes only

---

✅ Recommendations

1. Fix the incomplete sentence on line 41
2. Correct the "built time" typo on line 81
3. Fix indentation inconsistencies in Mermaid diagrams
4. Consider clarifying the "Drain Disabled" diagram to show the actor is recreated on the new version

---

Summary

This is a solid documentation addition that will help users understand version management. The issues found are minor and primarily editorial. Once the sentence is completed and typos are fixed, this will be ready to merge.

Overall Assessment: ✅ Approve with minor revisions suggested

[pkg-pr-new]

More templates

• actor-actions
• example-ai-agent
• example-ai-and-user-generated-actors-freestyle
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-cloudflare-workers-inline-client
• cross-actor-actions
• example-cursors
• example-cursors-raw-websocket
• custom-serverless
• example-sqlite
• example-elysia
• example-experimental-durable-streams-ai-agent
• hello-world
• example-hono
• hono-react
• example-kitchen-sink
• multi-region
• native-websockets
• next-js
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• scheduling
• state
• example-stream
• example-trpc

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@3901

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3901

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3901

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3901

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3901

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3901

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3901

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3901

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3901

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3901

commit: 82ade5d

[graphite-app]

Merge activity

• Jan 15, 5:08 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 15, 5:08 AM UTC: CI is running for this pull request on a draft pull request (#3915) due to your merge queue CI optimization settings.
• Jan 15, 5:09 AM UTC: Merged by the Graphite merge queue via draft PR: #3915.