guide/11-versioning.html
80 lines · 7091 bytes
1<!DOCTYPE html>
2<html lang="en">
3<head>
4<meta charset="utf-8">
5<meta name="viewport" content="width=device-width, initial-scale=1">
6<title>Versioning and upgrades · orgo</title>
7<meta name="description" content="What a version number promises, what it does not, and how to upgrade safely.">
8<link rel="icon" href="../favicon.svg" type="image/svg+xml">
9<link rel="stylesheet" href="../theme.css">
10<link rel="stylesheet" href="../syntax.css">
11<link rel="stylesheet" href="../style.css">
12</head>
13<body>
14<header class="site">
15<a class="site-title" href="../index.html">orgo</a>
16<nav>
17<a href="../install.html">Install</a>
18<a href="../quickstart.html">Quick start</a>
19<a href="index.html">Guide</a>
20</nav>
21</header>
22<main>
23<h1>Versioning and upgrades</h1>
24<p class="lede">The stable surface is what you build a site against, not what the code happens to do.</p>
25<nav class="toc" aria-label="On this page">
26<h2>On this page</h2>
27<ul>
28<li><a href="#the-stable-surface">The stable surface</a></li>
29<li><a href="#what-is-not-stable">What is not stable</a>
30<ul>
31<li><a href="#the-incremental-cache">The incremental cache</a></li>
32<li><a href="#rendered-html-details">Rendered HTML details</a></li>
33<li><a href="#what-a-built-in-theme-looks-like">What a built-in theme looks like</a></li>
34<li><a href="#the-rust-api">The Rust API</a></li>
35</ul></li>
36<li><a href="#the-compiler-floor">The compiler floor</a></li>
37<li><a href="#upgrading">Upgrading</a></li>
38</ul>
39</nav>
40<p>A generator you point at ten years of writing needs to be boring about compatibility. This page says exactly what is promised.</p>
41<h2 id="the-stable-surface">The stable surface</h2>
42<p>Changing any of this incompatibly requires a major version.</p>
43<table>
44<thead>
45<tr><th>Stable</th><th>What that covers</th></tr>
46</thead>
47<tbody>
48<tr><td><code class="verbatim">orgo.toml</code> keys</td><td>Their names, types and meaning.</td></tr>
49<tr><td>Template context</td><td><code class="verbatim">page</code>, <code class="verbatim">site</code>, <code class="verbatim">nav</code>, <code class="verbatim">root</code>, <code class="verbatim">pages</code>, <code class="verbatim">group</code>, <code class="verbatim">groups</code>, <code class="verbatim">paginator</code>, <code class="verbatim">stylesheet</code>, <code class="verbatim">theme</code>, and the <code class="verbatim">absolute</code>, <code class="verbatim">rfc822</code> and <code class="verbatim">truncate</code> filters.</td></tr>
50<tr><td>The CLI</td><td>Command names, flags and exit codes.</td></tr>
51<tr><td>URLs</td><td>How a source path becomes an output path, <code class="verbatim">#+SLUG:</code> included.</td></tr>
52</tbody>
53</table>
54<p><strong>URLs are on that list deliberately.</strong> A generator that quietly moves your pages breaks every link anyone has ever made to you, and no upgrade note fixes an inbound link.</p>
55<p>Adding things — a new config key, a new template variable — is a minor release. Nothing you already wrote stops working.</p>
56<h2 id="what-is-not-stable">What is not stable</h2>
57<p>Three things move freely, so the list above can hold still.</p>
58<h3 id="the-incremental-cache">The incremental cache</h3>
59<p><code class="verbatim"><output>/.orgo-cache.json</code> is versioned and discards itself on a mismatch. A cache format bump means one full rebuild, and nothing else. It is never a correctness dependency: a missing, stale or corrupt cache produces exactly the same site, more slowly.</p>
60<h3 id="rendered-html-details">Rendered HTML details</h3>
61<p>orgo aims at what Emacs exports from the same file, and closing a gap changes markup. That is the product working rather than a regression — but it is called out in the release notes every time, because your stylesheet is downstream of it.</p>
62<p>The class names the documentation names are the ones to write CSS against: <code class="verbatim">post-list</code>, <code class="verbatim">post-list-item</code>, <code class="verbatim">figure-number</code>, <code class="verbatim">table-number</code>, <code class="verbatim">section-number-N</code>, <code class="verbatim">footnote-ref</code>, <code class="verbatim">verbatim</code>, and the <code class="verbatim">on=/=off=/=trans</code> classes on checkbox items.</p>
63<h3 id="what-a-built-in-theme-looks-like">What a built-in theme looks like</h3>
64<p>The names — <code class="verbatim">plain</code>, <code class="verbatim">blog</code>, <code class="verbatim">wiki</code>, <code class="verbatim">docs</code> — and the fact that the chosen one is written to <code class="verbatim">theme.css</code> are stable. Its CSS is not: a theme is a starting point that improves between releases, and a site that cannot afford that should copy the stylesheet it likes into its own assets and stop naming a theme.</p>
65<h3 id="the-rust-api">The Rust API</h3>
66<p>The crate is on crates.io so the binary can be installed with <code class="verbatim">cargo install</code>. The library exists to serve the binary, and its types move as the tool does.</p>
67<h2 id="the-compiler-floor">The compiler floor</h2>
68<p>The MSRV is <strong>1.88</strong>, measured rather than assumed — which is how it came to be 1.88 rather than the 1.82 orgo's own code needs. The floor is set by dependencies, and a dependency raising its own is invisible until someone on an older compiler tries to build.</p>
69<p>Raising it is a minor version, never a patch.</p>
70<h2 id="upgrading">Upgrading</h2>
71<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">cargo</span></span><span class="meta function-call arguments shell"> install orgo <span class="comment line number-sign shell"><span class="punctuation definition comment begin shell">#</span></span><span class="comment line number-sign shell"> or download a release binary</span><span class="comment line number-sign shell">
72</span></span><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> build content<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> _site<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>no-cache</span><span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>strict</span></span></span></code></pre>
73<p><code class="verbatim">--no-cache</code> makes the first build after an upgrade a full one, so you are comparing the new version's output to the old version's output rather than to a cache written by a mixture of both. <code class="verbatim">--strict</code> turns a link that stopped resolving into a failure.</p>
74<p>If you keep your built site in version control, the diff after that command <strong>is</strong> the upgrade report, and the most useful review a generator can give you.</p>
75</main>
76<footer class="site">
77Built with orgo — these docs are an orgo site.
78</footer>
79</body>
80</html>