mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
653 lines
29 KiB
HTML
653 lines
29 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>migration_guide</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/migration_guide.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/migration_guide">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/migration_guide.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>migration_guide</h1><p class="lede">Comprehensive guide for migrating Protocol Buffer schemas safely while maintaining backward/forward compatibility.</p><h1>Protocol Buffer Schema Migration Guide</h1>
|
|
<p>Comprehensive guide for migrating Protocol Buffer schemas safely while maintaining backward/forward compatibility.</p>
|
|
<h2>Table of Contents</h2>
|
|
<ol><li><a href="#migration-strategy">Migration Strategy</a></li><li><a href="#breaking-vs-non-breaking-changes">Breaking vs Non-Breaking Changes</a></li><li><a href="#migration-patterns">Migration Patterns</a></li><li><a href="#version-by-version-examples">Version-by-Version Examples</a></li><li><a href="#testing-migrations">Testing Migrations</a></li><li><a href="#rollback-strategy">Rollback Strategy</a></li><li><a href="#production-checklist">Production Checklist</a></li></ol>
|
|
<hr>
|
|
<h2>Migration Strategy</h2>
|
|
<h3>Three-Phase Deployment</h3>
|
|
<p>The safest approach for schema evolution:</p>
|
|
<pre><code>Phase 1: Deploy Transitional Version (backward compatible)
|
|
- Add new fields as optional
|
|
- Mark old fields as deprecated
|
|
- Support both old and new patterns
|
|
|
|
Phase 2: Migrate Data and Clients
|
|
- Update all clients to use new fields
|
|
- Migrate existing data
|
|
- Monitor for deprecated field usage
|
|
|
|
Phase 3: Clean Up (potentially breaking)
|
|
- Remove deprecated fields (reserved)
|
|
- Drop transitional support code
|
|
- Deploy clean version</code></pre>
|
|
<h3>Compatibility Modes</h3>
|
|
<p><strong>Backward Compatible</strong> (most common):</p>
|
|
<ul><li>New servers can read old client messages</li><li>Safe for server-first deployments</li><li>Add optional fields, new enum values</li></ul>
|
|
<p><strong>Forward Compatible</strong> (less common):</p>
|
|
<ul><li>Old servers can read new client messages</li><li>Safe for client-first deployments</li><li>Never remove fields</li></ul>
|
|
<p><strong>Full Compatible</strong> (ideal):</p>
|
|
<ul><li>Both backward and forward compatible</li><li>Only add optional fields</li><li>Never remove anything</li></ul>
|
|
<hr>
|
|
<h2>Breaking vs Non-Breaking Changes</h2>
|
|
<h3>✅ Non-Breaking Changes</h3>
|
|
<pre><code class="lang-protobuf">// ✅ Adding optional fields
|
|
message User {
|
|
string id = 1;
|
|
string email = 2;
|
|
string name = 3; // New optional field
|
|
}
|
|
|
|
// ✅ Adding new enum values (at end)
|
|
enum Status {
|
|
STATUS_UNSPECIFIED = 0;
|
|
STATUS_ACTIVE = 1;
|
|
STATUS_INACTIVE = 2;
|
|
STATUS_ARCHIVED = 3; // New value
|
|
}
|
|
|
|
// ✅ Marking fields deprecated
|
|
message User {
|
|
string id = 1;
|
|
string email = 2;
|
|
string old_name = 3 [deprecated = true];
|
|
string display_name = 4; // Replacement
|
|
}
|
|
|
|
// ✅ Adding new messages/services
|
|
message UserProfile { // New message
|
|
string bio = 1;
|
|
}
|
|
|
|
// ✅ Reserving fields
|
|
message User {
|
|
reserved 10, 11, 12;
|
|
reserved "deleted_field", "removed_field";
|
|
}</code></pre>
|
|
<h3>❌ Breaking Changes</h3>
|
|
<pre><code class="lang-protobuf">// ❌ Removing fields without reservation
|
|
message User {
|
|
string id = 1;
|
|
string email = 2;
|
|
// string name = 3; // REMOVED - breaks compatibility!
|
|
}
|
|
|
|
// ❌ Changing field types
|
|
message User {
|
|
string id = 1;
|
|
int64 user_id = 2; // Was string, now int64 - BREAKS!
|
|
}
|
|
|
|
// ❌ Changing field numbers
|
|
message User {
|
|
string id = 1;
|
|
string email = 3; // Was 2, now 3 - BREAKS!
|
|
}
|
|
|
|
// ❌ Removing enum values
|
|
enum Status {
|
|
STATUS_UNSPECIFIED = 0;
|
|
STATUS_ACTIVE = 1;
|
|
// STATUS_INACTIVE = 2; // REMOVED - old data becomes invalid!
|
|
}
|
|
|
|
// ❌ Changing required/optional (proto2)
|
|
message User {
|
|
required string id = 1; // Was optional - BREAKS!
|
|
}
|
|
|
|
// ❌ Renaming fields (without json_name)
|
|
message User {
|
|
string id = 1;
|
|
string user_email = 2; // Was 'email' - JSON serialization BREAKS!
|
|
}</code></pre>
|
|
<hr>
|
|
<h2>Migration Patterns</h2>
|
|
<h3>Pattern 1: Adding a Field</h3>
|
|
<p><strong>Safe, backward compatible</strong></p>
|
|
<pre><code class="lang-protobuf">// Version 1
|
|
message User {
|
|
string id = 1;
|
|
string email = 2;
|
|
}
|
|
|
|
// Version 2 - Add optional field
|
|
message User {
|
|
string id = 1;
|
|
string email = 2;
|
|
string phone = 3; // New optional field
|
|
}</code></pre>
|
|
<p><strong>Behavior</strong>:</p>
|
|
<ul><li>Old clients: Ignore <code>phone</code> field (unknown field)</li><li>New clients: Can read old data (phone will be empty)</li><li>No deployment coordination needed</li></ul>
|
|
<hr>
|
|
<h3>Pattern 2: Replacing a Field</h3>
|
|
<p><strong>Requires three-phase deployment</strong></p>
|
|
<pre><code class="lang-protobuf">// Version 1 (Original)
|
|
message User {
|
|
string id = 1;
|
|
string email = 2;
|
|
string name = 3;
|
|
}
|
|
|
|
// Version 2 (Transitional - DEPLOY THIS FIRST)
|
|
message User {
|
|
string id = 1;
|
|
string email = 2;
|
|
string name = 3 [deprecated = true];
|
|
string display_name = 4; // New field
|
|
|
|
// Server code: Write to both, read from display_name preferring it
|
|
// Client code: Start writing to display_name, read from both
|
|
}
|
|
|
|
// Version 3 (Final - DEPLOY AFTER ALL CLIENTS UPDATED)
|
|
message User {
|
|
string id = 1;
|
|
string email = 2;
|
|
reserved 3;
|
|
reserved "name";
|
|
string display_name = 4;
|
|
}</code></pre>
|
|
<p><strong>Migration steps</strong>:</p>
|
|
<ol><li>Deploy v2 servers (support both fields)</li><li>Migrate existing data (name → display_name)</li><li>Update all clients to use display_name</li><li>Monitor: Ensure no clients use deprecated field</li><li>Deploy v3 (remove deprecated field)</li></ol>
|
|
<hr>
|
|
<h3>Pattern 3: Changing Field Type</h3>
|
|
<p><strong>Breaking change - requires new field</strong></p>
|
|
<pre><code class="lang-protobuf">// Version 1
|
|
message User {
|
|
string id = 1;
|
|
string age = 2; // Oops, should be int32
|
|
}
|
|
|
|
// Version 2 (Correct approach)
|
|
message User {
|
|
string id = 1;
|
|
string age = 2 [deprecated = true];
|
|
int32 age_years = 3; // New field with correct type
|
|
}
|
|
|
|
// Server migration code:
|
|
// if (user.age_years == 0 && user.age != "") {
|
|
// user.age_years = parseInt(user.age)
|
|
// }</code></pre>
|
|
<p><strong>Never do this</strong>:</p>
|
|
<pre><code class="lang-protobuf">// ❌ DON'T: Reuse field number with different type
|
|
message User {
|
|
string id = 1;
|
|
int32 age = 2; // Same number, different type - BREAKS!
|
|
}</code></pre>
|
|
<hr>
|
|
<h3>Pattern 4: Enum Evolution</h3>
|
|
<p><strong>Safe: Add values at end</strong></p>
|
|
<pre><code class="lang-protobuf">// Version 1
|
|
enum UserStatus {
|
|
USER_STATUS_UNSPECIFIED = 0;
|
|
USER_STATUS_ACTIVE = 1;
|
|
USER_STATUS_INACTIVE = 2;
|
|
}
|
|
|
|
// Version 2 - Add new values
|
|
enum UserStatus {
|
|
USER_STATUS_UNSPECIFIED = 0;
|
|
USER_STATUS_ACTIVE = 1;
|
|
USER_STATUS_INACTIVE = 2;
|
|
USER_STATUS_SUSPENDED = 3; // New value
|
|
USER_STATUS_DELETED = 4; // New value
|
|
}</code></pre>
|
|
<p><strong>Unsafe: Remove values</strong></p>
|
|
<pre><code class="lang-protobuf">// ❌ DON'T: Remove enum values
|
|
enum UserStatus {
|
|
USER_STATUS_UNSPECIFIED = 0;
|
|
USER_STATUS_ACTIVE = 1;
|
|
// USER_STATUS_INACTIVE = 2; // Removed - old data invalid!
|
|
}
|
|
|
|
// ✅ DO: Deprecate and reserve
|
|
enum UserStatus {
|
|
USER_STATUS_UNSPECIFIED = 0;
|
|
USER_STATUS_ACTIVE = 1;
|
|
reserved 2;
|
|
reserved "USER_STATUS_INACTIVE";
|
|
}</code></pre>
|
|
<hr>
|
|
<h3>Pattern 5: Nested Message Changes</h3>
|
|
<p><strong>Safe: Add optional nested message</strong></p>
|
|
<pre><code class="lang-protobuf">// Version 1
|
|
message User {
|
|
string id = 1;
|
|
string email = 2;
|
|
}
|
|
|
|
// Version 2
|
|
message User {
|
|
string id = 1;
|
|
string email = 2;
|
|
UserProfile profile = 3; // New nested message
|
|
}
|
|
|
|
message UserProfile {
|
|
string bio = 1;
|
|
string avatar_url = 2;
|
|
}</code></pre>
|
|
<hr>
|
|
<h3>Pattern 6: Service Evolution</h3>
|
|
<p><strong>Safe: Add new methods</strong></p>
|
|
<pre><code class="lang-protobuf">// Version 1
|
|
service UserService {
|
|
rpc GetUser(GetUserRequest) returns (GetUserResponse);
|
|
}
|
|
|
|
// Version 2
|
|
service UserService {
|
|
rpc GetUser(GetUserRequest) returns (GetUserResponse);
|
|
rpc ListUsers(ListUsersRequest) returns (ListUsersResponse); // New
|
|
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse); // New
|
|
}</code></pre>
|
|
<p><strong>Unsafe: Change method signatures</strong></p>
|
|
<pre><code class="lang-protobuf">// ❌ DON'T: Change request/response types
|
|
service UserService {
|
|
// Was: GetUser(GetUserRequest) returns (GetUserResponse)
|
|
rpc GetUser(GetUserRequestV2) returns (GetUserResponseV2); // BREAKS!
|
|
}
|
|
|
|
// ✅ DO: Add new method
|
|
service UserService {
|
|
rpc GetUser(GetUserRequest) returns (GetUserResponse);
|
|
rpc GetUserV2(GetUserRequestV2) returns (GetUserResponseV2); // New version
|
|
}</code></pre>
|
|
<hr>
|
|
<h2>Version-by-Version Examples</h2>
|
|
<p>See the example files for concrete evolution:</p>
|
|
<h3>V1 → V2 (Non-Breaking)</h3>
|
|
<ul><li><code>user_service_v1.proto</code> → <code>user_service_v2.proto</code></li><li>Added optional fields (display_name, role, email_verified)</li><li>Added new enum value (USER_STATUS_BANNED)</li><li>Marked field deprecated (name → display_name)</li></ul>
|
|
<h3>V2 → V3 (Breaking with Migration)</h3>
|
|
<ul><li><code>user_service_v2.proto</code> → <code>user_service_v3.proto</code></li><li>Removed deprecated field (properly reserved)</li><li>Changed role system (UserRole → Permissions)</li><li>Added nested profile message</li><li>Required coordinated deployment</li></ul>
|
|
<hr>
|
|
<h2>Testing Migrations</h2>
|
|
<h3>Compatibility Testing</h3>
|
|
<pre><code class="lang-python">#!/usr/bin/env python3
|
|
"""Test schema compatibility"""
|
|
|
|
import user_v1_pb2 as v1
|
|
import user_v2_pb2 as v2
|
|
|
|
# Test 1: V1 writer, V2 reader (backward compatibility)
|
|
user_v1 = v1.User(id="123", email="[email protected]", name="John")
|
|
data = user_v1.SerializeToString()
|
|
|
|
user_v2 = v2.User()
|
|
user_v2.ParseFromString(data)
|
|
|
|
assert user_v2.id == "123"
|
|
assert user_v2.email == "[email protected]"
|
|
assert user_v2.name == "John"
|
|
assert user_v2.display_name == "" # New field is empty
|
|
print("✅ Backward compatible: V1 → V2")
|
|
|
|
# Test 2: V2 writer, V1 reader (forward compatibility)
|
|
user_v2 = v2.User(
|
|
id="456",
|
|
email="[email protected]",
|
|
display_name="Jane Doe"
|
|
)
|
|
data = user_v2.SerializeToString()
|
|
|
|
user_v1 = v1.User()
|
|
user_v1.ParseFromString(data)
|
|
|
|
assert user_v1.id == "456"
|
|
assert user_v1.email == "[email protected]"
|
|
# V1 ignores unknown field (display_name)
|
|
print("✅ Forward compatible: V2 → V1")</code></pre>
|
|
<h3>Testing with Multiple Versions</h3>
|
|
<pre><code class="lang-bash">#!/bin/bash
|
|
# Test all version combinations
|
|
|
|
# Generate code for all versions
|
|
for v in v1 v2 v3; do
|
|
protoc --python_out=. user_service_${v}.proto
|
|
done
|
|
|
|
# Run compatibility tests
|
|
python test_v1_v2_compat.py
|
|
python test_v2_v3_compat.py
|
|
python test_v1_v3_compat.py # Should fail if breaking changes
|
|
|
|
# Validate with tools
|
|
./scripts/analyze_schema_compatibility.py \
|
|
--baseline user_service_v1.proto \
|
|
--current user_service_v2.proto \
|
|
--mode full
|
|
|
|
./scripts/analyze_schema_compatibility.py \
|
|
--baseline user_service_v2.proto \
|
|
--current user_service_v3.proto \
|
|
--mode backward</code></pre>
|
|
<hr>
|
|
<h2>Rollback Strategy</h2>
|
|
<h3>Rollback Scenarios</h3>
|
|
<p><strong>Scenario 1: Non-Breaking Change Rollback</strong></p>
|
|
<pre><code>V2 deployment failed → Rollback to V1
|
|
- Safe: V1 code can read V2 data (ignores new fields)
|
|
- No data migration needed</code></pre>
|
|
<p><strong>Scenario 2: Breaking Change Rollback</strong></p>
|
|
<pre><code>V3 deployment failed → Rollback to V2
|
|
- Risk: V2 code may not understand V3 data
|
|
- Need database rollback or data migration
|
|
- Always test rollback path before deployment!</code></pre>
|
|
<h3>Rollback Testing</h3>
|
|
<pre><code class="lang-bash">#!/bin/bash
|
|
# Test rollback scenarios
|
|
|
|
# 1. Deploy V2, generate data
|
|
deploy_v2
|
|
generate_test_data_v2
|
|
|
|
# 2. Rollback to V1
|
|
rollback_v1
|
|
|
|
# 3. Verify V1 can read V2 data
|
|
test_v1_reads_v2_data || exit 1
|
|
|
|
# 4. Verify no errors in logs
|
|
check_application_logs || exit 1
|
|
|
|
echo "✅ Rollback test passed"</code></pre>
|
|
<hr>
|
|
<h2>Production Checklist</h2>
|
|
<p>Before deploying schema changes:</p>
|
|
<h3>Pre-Deployment</h3>
|
|
<ul><li>[ ] <strong>Analyze compatibility</strong></li></ul>
|
|
<p> ``<code>bash ./scripts/analyze_schema_compatibility.py \ --baseline prod_version.proto \ --current new_version.proto \ --mode backward </code>``</p>
|
|
<ul><li>[ ] <strong>Run validation</strong></li></ul>
|
|
<p> ``<code>bash ./scripts/validate_proto_schemas.py \ --proto-file new_version.proto </code>``</p>
|
|
<ul><li>[ ] <strong>Generate and test code</strong></li></ul>
|
|
<p> ``<code>bash ./scripts/generate_proto_code.py \ --proto-file new_version.proto \ --language python,go \ --validate </code>``</p>
|
|
<ul><li>[ ] <strong>Review breaking changes</strong></li><li>Document all breaking changes</li><li>Plan migration strategy (3-phase if needed)</li><li>Communicate to all teams</li></ul>
|
|
<ul><li>[ ] <strong>Test compatibility</strong></li><li>Write compatibility tests</li><li>Test old client → new server</li><li>Test new client → old server</li><li>Test rollback scenario</li></ul>
|
|
<ul><li>[ ] <strong>Update documentation</strong></li><li>Update CHANGELOG</li><li>Document migration steps</li><li>Update API documentation</li></ul>
|
|
<h3>Deployment</h3>
|
|
<ul><li>[ ] <strong>Phase 1: Deploy transitional version</strong></li><li>Supports both old and new patterns</li><li>Monitor logs for errors</li><li>Verify backward compatibility</li></ul>
|
|
<ul><li>[ ] <strong>Phase 2: Migrate data and clients</strong></li><li>Run data migration scripts</li><li>Deploy updated clients</li><li>Monitor deprecated field usage</li></ul>
|
|
<ul><li>[ ] <strong>Phase 3: Deploy final version</strong></li><li>Remove deprecated code</li><li>Clean up database</li><li>Update monitoring dashboards</li></ul>
|
|
<h3>Post-Deployment</h3>
|
|
<ul><li>[ ] <strong>Monitor metrics</strong></li><li>Deserialization errors</li><li>Unknown field warnings</li><li>Application errors</li></ul>
|
|
<ul><li>[ ] <strong>Verify data integrity</strong></li><li>Sample data checks</li><li>Field population rates</li><li>Data type correctness</li></ul>
|
|
<ul><li>[ ] <strong>Update schema registry</strong></li><li>Register new schema version</li><li>Verify compatibility level</li><li>Update documentation</li></ul>
|
|
<hr>
|
|
<h2>Common Pitfalls</h2>
|
|
<h3>1. Reusing Field Numbers</h3>
|
|
<p><strong>❌ DON'T:</strong></p>
|
|
<pre><code class="lang-protobuf">message User {
|
|
string id = 1;
|
|
// Removed: string email = 2;
|
|
int32 age = 2; // Reused number 2 - DANGER!
|
|
}</code></pre>
|
|
<p><strong>Why it's bad</strong>: Old data with email="[email protected]" will be parsed as age, causing corruption.</p>
|
|
<p><strong>✅ DO:</strong></p>
|
|
<pre><code class="lang-protobuf">message User {
|
|
string id = 1;
|
|
reserved 2;
|
|
reserved "email";
|
|
int32 age = 3; // New number
|
|
}</code></pre>
|
|
<h3>2. Changing JSON Field Names</h3>
|
|
<p><strong>❌ DON'T:</strong></p>
|
|
<pre><code class="lang-protobuf">message User {
|
|
string user_identifier = 1; // Was 'id'
|
|
}</code></pre>
|
|
<p><strong>Why it's bad</strong>: JSON serialization uses field names, breaking JSON clients.</p>
|
|
<p><strong>✅ DO:</strong></p>
|
|
<pre><code class="lang-protobuf">message User {
|
|
string user_identifier = 1 [json_name = "id"]; // Keep JSON name
|
|
}</code></pre>
|
|
<h3>3. Assuming Zero Values</h3>
|
|
<p><strong>❌ DON'T:</strong></p>
|
|
<pre><code class="lang-protobuf">enum Status {
|
|
STATUS_ACTIVE = 0; // Bad: zero should be unspecified
|
|
STATUS_INACTIVE = 1;
|
|
}</code></pre>
|
|
<p><strong>Why it's bad</strong>: Cannot distinguish between unset and explicitly set to zero.</p>
|
|
<p><strong>✅ DO:</strong></p>
|
|
<pre><code class="lang-protobuf">enum Status {
|
|
STATUS_UNSPECIFIED = 0;
|
|
STATUS_ACTIVE = 1;
|
|
STATUS_INACTIVE = 2;
|
|
}</code></pre>
|
|
<hr>
|
|
<h2>Tools and Resources</h2>
|
|
<h3>Validation Tools</h3>
|
|
<pre><code class="lang-bash"># Buf: Modern protobuf tool
|
|
buf lint
|
|
buf breaking --against '.git#branch=main'
|
|
|
|
# Custom scripts
|
|
./scripts/validate_proto_schemas.py --proto-dir protos
|
|
./scripts/analyze_schema_compatibility.py --baseline v1.proto --current v2.proto</code></pre>
|
|
<h3>Monitoring</h3>
|
|
<p>Set up alerts for:</p>
|
|
<ul><li>Protobuf deserialization errors</li><li>Unknown field warnings</li><li>Deprecated field usage</li><li>Schema registry rejections</li></ul>
|
|
<h3>Documentation</h3>
|
|
<ul><li>Keep CHANGELOG.md updated</li><li>Document breaking changes prominently</li><li>Provide migration guides for major changes</li><li>Update API documentation automatically</li></ul>
|
|
<hr>
|
|
<h2>Summary</h2>
|
|
<p><strong>Golden Rules for Safe Schema Evolution:</strong></p>
|
|
<ol><li>✅ Always add fields, never remove (use reserved)</li><li>✅ New fields must be optional</li><li>✅ Never change field numbers</li><li>✅ Never reuse field numbers</li><li>✅ Enum zero value = UNSPECIFIED</li><li>✅ Test backward compatibility</li><li>✅ Use three-phase deployment for breaking changes</li><li>✅ Monitor after deployment</li><li>✅ Have rollback plan</li><li>✅ Communicate changes to all teams</li></ol>
|
|
<p><strong>When in doubt</strong>: Add a new field rather than modifying an existing one.</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/migration_guide.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |