<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/CONTRIBUTING.md - fork/helix @ 25.07</title>
<meta name="description" content="docs/CONTRIBUTING.md in fork/helix at 25.07.">
<meta property="og:title" content="docs/CONTRIBUTING.md - fork/helix @ 25.07">
<meta property="og:description" content="docs/CONTRIBUTING.md in fork/helix at 25.07.">
<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.07" data-tip="5cda70e86637c376bdfaaf3383872e44d7622ff8">
<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">omahs</span><span class="commit-message" data-commit="bfd2c727159dc12e12085546586d3242195e1c04">fix: typos (#13505)</span><span class="snapshot-sha sha" data-commit="bfd2c727159dc12e12085546586d3242195e1c04">bfd2c727</span><time datetime="2025-05-10T17:36:17+02:00" title="2025-05-10 17:36:17 +0200">2025-05-10</time></p>
<header class="topbar"><details class="switcher"><summary>25.07</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 href="/fork/helix/ref/25.01.1/">25.01.1</a><a class="current" 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.07/tree/docs/">docs</a> / <span class="cur">CONTRIBUTING.md</span></nav>
<span class="view-stats"><span>3.9 KiB</span><span>80 lines</span></span><span class="actions"><a class="raw" href="/fork/helix/raw/92ae84a6932dbf6714beaa2adfabadfa008b851f/docs/CONTRIBUTING.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"><h1>Contributing</h1>
<p>Contributors are very welcome! <strong>No contribution is too small and all contributions are valued.</strong></p>
<p>Some suggestions to get started:</p>
<ul>
<li>You can look at the <a href="https://github.com/helix-editor/helix/labels/E-easy">good first issue</a> label on the issue tracker.</li>
<li>Help with packaging on various distributions needed!</li>
<li>To use print debugging to the <a href="https://github.com/helix-editor/helix/wiki/FAQ#access-the-log-file">Helix log file</a>, you must:
<ul>
<li>Print using <code>log::info!</code>, <code>warn!</code>, or <code>error!</code>. (<code>log::info!("helix!")</code>)</li>
<li>Pass the appropriate verbosity level option for the desired log level. (<code>hx -v &lt;file&gt;</code> for info, more <code>v</code>s for higher verbosity)</li>
<li>Want to display the logs in a separate file instead of using the <code>:log-open</code> command in your compiled Helix editor? Start your debug version with <code>cargo run -- --log foo.log</code> and in a new terminal use <code>tail -f foo.log</code></li>
</ul>
</li>
<li>Instead of running a release version of Helix, while developing you may want to run in debug mode with <code>cargo run</code> which is way faster to compile</li>
<li>Looking for even faster compile times? Give a try to <a href="https://github.com/rui314/mold">mold</a></li>
<li>If your preferred language is missing, integrating a tree-sitter grammar for
it and defining syntax highlight queries for it is straightforward and
doesn't require much knowledge of the internals.</li>
<li>If you don't use the Nix development shell and are getting your rust-analyzer binary from rustup, you may need to run <code>rustup component add rust-analyzer</code>.
This is because <code>rust-toolchain.toml</code> selects our MSRV for the development toolchain but doesn't download the matching rust-analyzer automatically.</li>
</ul>
<p>We provide an <a href="/fork/helix/ref/25.07/blob/docs/architecture.md">architecture.md</a> that should give you
a good overview of the internals.</p>
<h1>Auto generated documentation</h1>
<p>Some parts of <a href="https://docs.helix-editor.com/">the book</a> are autogenerated from the code itself,
like the list of <code>:commands</code> and supported languages. To generate these
files, run</p>
<pre class="language-bash"><a-f>cargo</a-f> xtask docgen</pre>
<p>inside the project. We use <a href="https://github.com/matklad/cargo-xtask">xtask</a> as an ad-hoc task runner.</p>
<p>To preview the book itself, install <a href="https://rust-lang.github.io/mdBook/guide/installation.html">mdbook</a>. Then, run</p>
<pre class="language-bash"><a-f>mdbook</a-f> serve book</pre>
<p>and visit <a href="http://localhost:3000">http://localhost:3000</a>.</p>
<h1>Testing</h1>
<h2>Unit tests/Documentation tests</h2>
<p>Run <code>cargo test --workspace</code> to run unit tests and documentation tests in all packages.</p>
<h2>Integration tests</h2>
<p>Integration tests for helix-term can be run with <code>cargo integration-test</code>. Code
contributors are strongly encouraged to write integration tests for their code.
Existing tests can be used as examples. Helpers can be found in
<a href="/fork/helix/ref/25.07/blob/helix-term/tests/test/helpers.rs">helpers.rs</a>. The log level can be set with the <code>HELIX_LOG_LEVEL</code>
environment variable, e.g. <code>HELIX_LOG_LEVEL=debug cargo integration-test</code>.</p>
<p>Contributors using MacOS might encounter <code>Too many open files (os error 24)</code>
failures while running integration tests. This can be resolved by increasing
the default value (e.g. to <code>10240</code> from <code>256</code>) by running <code>ulimit -n 10240</code>.</p>
<h2>Minimum Stable Rust Version (MSRV) Policy</h2>
<p>Helix keeps an intentionally low MSRV for the sake of easy building and packaging
downstream. We follow <a href="https://firefox-source-docs.mozilla.org/writing-rust-code/update-policy.html">Firefox's MSRV policy</a>. Once Firefox's MSRV increases we
may bump ours as well, but be sure to check that popular distributions like Ubuntu
package the new MSRV version. When increasing the MSRV, update these three places:</p>
<ul>
<li>the <code>workspace.package.rust-version</code> key in <code>Cargo.toml</code> in the repository root</li>
<li>the <code>env.MSRV</code> key at the top of <code>.github/workflows/build.yml</code></li>
<li>the <code>toolchain.channel</code> key in <code>rust-toolchain.toml</code></li>
</ul>
</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>Contributing</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">Contributors are very welcome! **No contribution is too small and all contributions are valued.**</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">Some suggestions to get started:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"><a-p>- </a-p>You can look at the [good first issue][good-first-issue] label on the issue tracker.</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>Help with packaging on various distributions needed!</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>To use print debugging to the [Helix log file][log-file], you must:</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>Print using `log::info!`, `warn!`, or `error!`. (`log::info!(&quot;helix!&quot;)`)</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>Pass the appropriate verbosity level option for the desired log level. (`hx -v &lt;file&gt;` for info, more `v`s for higher verbosity)</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>Want to display the logs in a separate file instead of using the `:log-open` command in your compiled Helix editor? Start your debug version with `cargo run -- --log foo.log` and in a new terminal use `tail -f foo.log`</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>Instead of running a release version of Helix, while developing you may want to run in debug mode with `cargo run` which is way faster to compile</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>Looking for even faster compile times? Give a try to [mold](https://github.com/rui314/mold)</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>If your preferred language is missing, integrating a tree-sitter grammar for</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>  it and defining syntax highlight queries for it is straightforward and</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>  doesn&#39;t require much knowledge of the internals.</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>If you don&#39;t use the Nix development shell and are getting your rust-analyzer binary from rustup, you may need to run `rustup component add rust-analyzer`.</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>This is because `rust-toolchain.toml` selects our MSRV for the development toolchain but doesn&#39;t download the matching rust-analyzer automatically.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></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>We provide an [architecture.md][architecture.md] that should give you</a-p></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 good overview of the internals.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"></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><a-tt>Auto generated documentation</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"></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>Some parts of [the book][docs] are autogenerated from the code itself,</a-p></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>like the list of `:commands` and supported languages. To generate these</a-p></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>files, run</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"></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><a-tl>shell</a-tl></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>cargo xtask docgen</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>inside the project. We use [xtask][xtask] as an ad-hoc task runner.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>To preview the book itself, install [mdbook][mdbook]. Then, run</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></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>```</a-p><a-tl>shell</a-tl></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>mdbook serve book</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>```</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>and visit [http://localhost:3000](http://localhost:3000).</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"></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><a-tt>Testing</a-tt></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>## </a-p><a-tt>Unit tests/Documentation tests</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"></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>Run `cargo test --workspace` to run unit tests and documentation tests in all packages.</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"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-p>## </a-p><a-tt>Integration tests</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"></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>Integration tests for helix-term can be run with `cargo integration-test`. Code</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>contributors are strongly encouraged to write integration tests for their code.</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"><a-p>Existing tests can be used as examples. Helpers can be found in</a-p></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>[helpers.rs][helpers.rs]. The log level can be set with the `HELIX_LOG_LEVEL`</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>environment variable, e.g. `HELIX_LOG_LEVEL=debug cargo integration-test`.</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>Contributors using MacOS might encounter `Too many open files (os error 24)`</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>failures while running integration tests. This can be resolved by increasing</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>the default value (e.g. to `10240` from `256`) by running `ulimit -n 10240`.</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>## </a-p><a-tt>Minimum Stable Rust Version (MSRV) Policy</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"><a-p>Helix keeps an intentionally low MSRV for the sake of easy building and packaging</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>downstream. We follow [Firefox&#39;s MSRV policy]. Once Firefox&#39;s MSRV increases we</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"><a-p>may bump ours as well, but be sure to check that popular distributions like Ubuntu</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>package the new MSRV version. When increasing the MSRV, update these three places:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"><a-p>* the `workspace.package.rust-version` key in `Cargo.toml` in the repository root</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>* the `env.MSRV` key at the top of `.github/workflows/build.yml`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"><a-p>* the `toolchain.channel` key in `rust-toolchain.toml`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"><a-tu>[Firefox&#39;s MSRV policy]</a-tu><a-p>: </a-p><a-tu>https://firefox-source-docs.mozilla.org/writing-rust-code/update-policy.html</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"><a-tu>[good-first-issue]</a-tu><a-p>: </a-p><a-tu>https://github.com/helix-editor/helix/labels/E-easy</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"><a-tu>[log-file]</a-tu><a-p>: </a-p><a-tu>https://github.com/helix-editor/helix/wiki/FAQ#access-the-log-file</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"><a-tu>[architecture.md]</a-tu><a-p>: </a-p><a-tu>./architecture.md</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"><a-tu>[docs]</a-tu><a-p>: </a-p><a-tu>https://docs.helix-editor.com/</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-tu>[xtask]</a-tu><a-p>: </a-p><a-tu>https://github.com/matklad/cargo-xtask</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"><a-tu>[mdbook]</a-tu><a-p>: </a-p><a-tu>https://rust-lang.github.io/mdBook/guide/installation.html</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"><a-tu>[helpers.rs]</a-tu><a-p>: </a-p><a-tu>../helix-term/tests/test/helpers.rs</a-tu></span></span></pre></div></div>
</main>
</body>
</html>
