<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/releases.md - fork/helix @ 25.01.1</title>
<meta name="description" content="docs/releases.md in fork/helix at 25.01.1.">
<meta property="og:title" content="docs/releases.md - fork/helix @ 25.01.1">
<meta property="og:description" content="docs/releases.md in fork/helix at 25.01.1.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="25.01.1" data-tip="e7ac2fcdecfdbf43a4f772e7f7c163b43b3d0b9b">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/helix</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/helix</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Michael Davis</span><span class="commit-message" data-commit="ea17b9edb708bc5ea26fec95dda66a6f45753545">release docs: Fix `git push` command for the release tag</span><span class="snapshot-sha sha" data-commit="ea17b9edb708bc5ea26fec95dda66a6f45753545">ea17b9ed</span><time datetime="2024-12-22T09:45:16-05:00" title="2024-12-22 09:45:16 -0500">2024-12-22</time></p>
<header class="topbar"><details class="switcher"><summary>25.01.1</summary><div class="menu"><strong>branches</strong><a href="/fork/helix/ref/master/">master</a><strong>tags</strong><a href="/fork/helix/ref/23.05/">23.05</a><a href="/fork/helix/ref/23.10/">23.10</a><a href="/fork/helix/ref/24.03/">24.03</a><a href="/fork/helix/ref/24.07/">24.07</a><a href="/fork/helix/ref/25.01/">25.01</a><a class="current" href="/fork/helix/ref/25.01.1/">25.01.1</a><a href="/fork/helix/ref/25.07/">25.07</a><a href="/fork/helix/ref/25.07.1/">25.07.1</a><a class="all" href="/fork/helix/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/helix/">helix</a> / <a href="/fork/helix/ref/25.01.1/tree/docs/">docs</a> / <span class="cur">releases.md</span></nav>
<span class="view-stats"><span>3.1 KiB</span><span>66 lines</span></span><span class="actions"><a class="raw" href="/fork/helix/raw/41b523c5295bddf3883f9b860037369a89f982f2/docs/releases.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h2>Checklist</h2>
<p>Helix releases are versioned in the Calendar Versioning scheme:
<code>YY.0M(.MICRO)</code>, for example, <code>22.05</code> for May of 2022, or in a patch release,
<code>22.05.1</code>. In these instructions we'll use <code>&lt;tag&gt;</code> as a placeholder for the tag
being published.</p>
<ul>
<li>Merge the PR with the release updates. That branch should:
<ul>
<li>Update the version:
<ul>
<li>Update the <code>workspace.package.version</code> key in <code>Cargo.toml</code>. Cargo only accepts
SemVer versions so a CalVer version of <code>22.07</code> for example must be formatted
as <code>22.7.0</code>. Patch/bugfix releases should increment the SemVer patch number. A
patch release for 22.07 would be <code>22.7.1</code>.</li>
<li>Run <code>cargo check</code> and commit the resulting change to <code>Cargo.lock</code></li>
</ul>
</li>
<li>Add changelog notes to <code>CHANGELOG.md</code></li>
<li>Add new <code>&lt;release&gt;</code> entry in <code>contrib/Helix.appdata.xml</code> with release information according to the <a href="https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Releases.html">AppStream spec</a></li>
</ul>
</li>
<li>Tag and push
<ul>
<li>Switch to master and pull</li>
<li><code>git tag -s -m "&lt;tag&gt;" -a &lt;tag&gt; &amp;&amp; git push origin &lt;tag&gt;</code> (note the <code>-s</code> which signs the tag)</li>
</ul>
</li>
<li>Wait for the Release CI to finish
<ul>
<li>It will automatically turn the git tag into a GitHub release when it uploads artifacts</li>
</ul>
</li>
<li>Edit the new release
<ul>
<li>Use <code>&lt;tag&gt;</code> as the title</li>
<li>Link to the changelog and release notes</li>
</ul>
</li>
<li>Merge the release notes PR</li>
<li>Download the macos and linux binaries and update the <code>sha256</code>s in the <a href="https://github.com/Homebrew/homebrew-core/blob/master/Formula/h/helix.rb">homebrew formula</a>
<ul>
<li>Use <code>sha256sum</code> on the downloaded <code>.tar.xz</code> files to determine the hash</li>
</ul>
</li>
<li>Link to the release notes in this-week-in-rust
<ul>
<li><a href="https://github.com/rust-lang/this-week-in-rust/pull/3300">Example PR</a></li>
</ul>
</li>
<li>Post to reddit
<ul>
<li><a href="https://www.reddit.com/r/rust/comments/uzp5ze/helix_editor_2205_released/">Example post</a></li>
</ul>
</li>
</ul>
<h2>Changelog Curation</h2>
<p>The changelog is currently created manually by reading through commits in the
log since the last release. GitHub's compare view is a nice way to approach
this. For example, when creating the 22.07 release notes, this compare link
may be used</p>
<pre>https://github.com/helix-editor/helix/compare/22.05...master
</pre>
<p>Either side of the triple-dot may be replaced with an exact revision, so if
you wish to incrementally compile the changelog, you can tackle a weeks worth
or so, record the revision where you stopped, and use that as a starting point
next week:</p>
<pre>https://github.com/helix-editor/helix/compare/7706a4a0d8b67b943c31d0c5f7b00d357b5d838d...master
</pre>
<p>A work-in-progress commit for a changelog might look like
<a href="https://github.com/helix-editor/helix/commit/831adfd4c709ca16b248799bfef19698d5175e55">this example</a>.</p>
<p>Not every PR or commit needs a blurb in the changelog. Each release section
tends to have a blurb that links to a GitHub comparison between release
versions for convenience:</p>
<blockquote>
<p>As usual, the following is a summary of each of the changes since the last
release. For the full log, check out the git log.</p>
</blockquote>
<p>Typically, small changes like dependencies or documentation updates, refactors,
or meta changes like GitHub Actions work are left out.</p>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>##</a-p> <a-tt>Checklist</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">Helix releases are versioned in the Calendar Versioning scheme:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">`YY.0M(.MICRO)`, for example, `22.05` for May of 2022, or in a patch release,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">`22.05.1`. In these instructions we&#39;ll use `&lt;tag&gt;` as a placeholder for the tag</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">being published.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"><a-p>* </a-p>Merge the PR with the release updates. That branch should:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text"><a-p>    * </a-p>Update the version:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"><a-p>        * </a-p>Update the `workspace.package.version` key in `Cargo.toml`. Cargo only accepts</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"><a-p>          </a-p>SemVer versions so a CalVer version of `22.07` for example must be formatted</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"><a-p>          </a-p>as `22.7.0`. Patch/bugfix releases should increment the SemVer patch number. A</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"><a-p>          </a-p>patch release for 22.07 would be `22.7.1`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"><a-p>        * </a-p>Run `cargo check` and commit the resulting change to `Cargo.lock`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"><a-p>    * </a-p>Add changelog notes to `CHANGELOG.md`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"><a-p>    * </a-p>Add new `&lt;release&gt;` entry in `contrib/Helix.appdata.xml` with release information according to the [AppStream spec](https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Releases.html)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"><a-p>* </a-p>Tag and push</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"><a-p>    * </a-p>Switch to master and pull</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>    * </a-p>`git tag -s -m &quot;&lt;tag&gt;&quot; -a &lt;tag&gt; &amp;&amp; git push origin &lt;tag&gt;` (note the `-s` which signs the tag)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"><a-p>* </a-p>Wait for the Release CI to finish</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"><a-p>    * </a-p>It will automatically turn the git tag into a GitHub release when it uploads artifacts</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>* </a-p>Edit the new release</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>    * </a-p>Use `&lt;tag&gt;` as the title</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"><a-p>    * </a-p>Link to the changelog and release notes</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"><a-p>* </a-p>Merge the release notes PR</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>* </a-p>Download the macos and linux binaries and update the `sha256`s in the [homebrew formula]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>    * </a-p>Use `sha256sum` on the downloaded `.tar.xz` files to determine the hash</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>* </a-p>Link to the release notes in this-week-in-rust</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"><a-p>    * </a-p>[Example PR](https://github.com/rust-lang/this-week-in-rust/pull/3300)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>* </a-p>Post to reddit</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>    * </a-p>[Example post](https://www.reddit.com/r/rust/comments/uzp5ze/helix_editor_2205_released/)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"><a-tu>[homebrew formula]</a-tu><a-p>: </a-p><a-tu>https://github.com/Homebrew/homebrew-core/blob/master/Formula/h/helix.rb</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"><a-p>## </a-p><a-tt>Changelog Curation</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"><a-p>The changelog is currently created manually by reading through commits in the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>log since the last release. GitHub&#39;s compare view is a nice way to approach</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"><a-p>this. For example, when creating the 22.07 release notes, this compare link</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>may be used</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>https://github.com/helix-editor/helix/compare/22.05...master</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"><a-p>Either side of the triple-dot may be replaced with an exact revision, so if</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>you wish to incrementally compile the changelog, you can tackle a weeks worth</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>or so, record the revision where you stopped, and use that as a starting point</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>next week:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"><a-p>https://github.com/helix-editor/helix/compare/7706a4a0d8b67b943c31d0c5f7b00d357b5d838d...master</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"><a-p>A work-in-progress commit for a changelog might look like</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>[this example](https://github.com/helix-editor/helix/commit/831adfd4c709ca16b248799bfef19698d5175e55).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-p>Not every PR or commit needs a blurb in the changelog. Each release section</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>tends to have a blurb that links to a GitHub comparison between release</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"><a-p>versions for convenience:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>&gt; As usual, the following is a summary of each of the changes since the last</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"><a-p>&gt; </a-p>release. For the full log, check out the git log.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text">Typically, small changes like dependencies or documentation updates, refactors,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text">or meta changes like GitHub Actions work are left out.</span></span></pre></div></div>
</main>
</body>
</html>
