<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>COMPATIBILITY.md - fork/rules_rust @ 0.6.0</title>
<meta name="description" content="COMPATIBILITY.md in fork/rules_rust at 0.6.0.">
<meta property="og:title" content="COMPATIBILITY.md - fork/rules_rust @ 0.6.0">
<meta property="og:description" content="COMPATIBILITY.md in fork/rules_rust at 0.6.0.">
<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="0.6.0" data-tip="91466fc0d102b1754d39d0e9e2cffdb48e7671d0">
<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/rules_rust</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/rules_rust</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Marcel Hlopko</span><span class="commit-message" data-commit="e6e2e1fa6ca487e8ff3ec789bbfade6c87bc74d2">Define backwards compatibility policy for `rules_rust` (#832)</span><span class="snapshot-sha sha" data-commit="e6e2e1fa6ca487e8ff3ec789bbfade6c87bc74d2">e6e2e1fa</span><time datetime="2021-08-12T09:13:55+02:00" title="2021-08-12 09:13:55 +0200">2021-08-12</time></p>
<header class="topbar"><details class="switcher"><summary>0.6.0</summary><div class="menu"><strong>branches</strong><a href="/fork/rules_rust/ref/cleanup/">cleanup</a><a href="/fork/rules_rust/ref/gh-pages/">gh-pages</a><a href="/fork/rules_rust/ref/main/">main</a><a href="/fork/rules_rust/ref/patching/">patching</a><a href="/fork/rules_rust/ref/rust-analyzer/">rust-analyzer</a><strong>tags</strong><a href="/fork/rules_rust/ref/0.10.0/">0.10.0</a><a href="/fork/rules_rust/ref/0.11.0/">0.11.0</a><a href="/fork/rules_rust/ref/0.5.0/">0.5.0</a><a class="current" href="/fork/rules_rust/ref/0.6.0/">0.6.0</a><a href="/fork/rules_rust/ref/0.7.0/">0.7.0</a><a href="/fork/rules_rust/ref/0.8.0/">0.8.0</a><a href="/fork/rules_rust/ref/0.8.1/">0.8.1</a><a href="/fork/rules_rust/ref/0.9.0/">0.9.0</a><a class="all" href="/fork/rules_rust/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/rules_rust/">rules_rust</a> / <span class="cur">COMPATIBILITY.md</span></nav>
<span class="view-stats"><span>5.4 KiB</span><span>109 lines</span></span><span class="actions"><a class="raw" href="/fork/rules_rust/raw/afb44bd35081472f57c9d1962ba183d0b3dcc0ae/COMPATIBILITY.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><code>rules_rust</code> backwards compatibility policy</h1>
<p>This document defines the backwards compatibility policy for rules_rust and
defines the process for making compatibility breaking changes. Any exception to
this process will have to be thoroughly discussed and there will have to be a
consensus between maintainers that the exception should be granted.</p>
<h2>What is a compatibility breaking change?</h2>
<p>A backwards compatible change has the property that a build that is green,
correct, is using stable APIs of <code>rules_rust</code>, and is using a supported version
of Bazel before the change is still green and correct after the change. In
practice it means that users should not have to modify their project source
files, their <code>BUILD</code> files, their <code>bzl</code> files, their <code>rust_toolchain</code>
definitions, their platform definitions, or their build settings.</p>
<p>A backwards compatible release has the property that it only contains backward
compatible changes.</p>
<p><code>rules_rust</code> follow <a href="https://semver.org/">SemVer 2.0.0</a>. <code>rules_rust</code> promise
that all minor version number and patch version number releases only contain
backwards compatible changes.</p>
<p><code>rules_rust</code> don't make any guarantees about compatibility between a released
version and the state of the <code>rules_rust</code> at HEAD.</p>
<p>Backwards incompatible changes will have to follow a process in order to be
released. Users will be given at least one release where the old behavior is
still present but deprecated to allow smooth migration of their project to the
new behavior.</p>
<h3>Compatibility before 1.0</h3>
<p>All minor version number releases before version 1.0 can be backwards incompatible.
Backwards incompatible changes still have to follow the the process, but minimum
time for migration is reduced to 2 weeks.</p>
<h2>What Bazel versions are supported?</h2>
<p><code>rules_rust</code> support the current Bazel LTS at the time of a <code>rules_rust</code>
release.</p>
<p>Support for the current Bazel rolling release is on the best effort basis. If
the CI build of <code>rules_rust</code> against the current Bazel rolling release is green,
it has to stay green. If the build is already red (because the new Bazel rolling
release had incompatible changes that broke <code>rules_rust</code>), it is acceptable to
merge PRs leaving the build red as long as the reason for failure remains the
same. We hope red CI with the current rolling release will be rare.</p>
<p><code>rules_rust</code> don't promise all new <code>rules_rust</code> features available to the
current Bazel rolling release to be be available to the current Bazel LTS
release (because Bazel compatibility policy doesn't allow us to make that
promise, and some new features of <code>rules_rust</code> require new Bazel features that
are only available in Bazel rolling releases). <code>rules_rust</code> will aim that new
features available to the current Bazel rolling release will be available to the
next Bazel LTS release at latest.</p>
<p>Whenever there is a new Bazel LTS release, all releases of <code>rules_rust</code> will maintain
support for the older LTS version for at least 3 months unless Bazel doesn't allow this.</p>
<h2>What host platforms are supported?</h2>
<p>Platforms subject to backwards compatibility policy are
<code>x86_64-unknown-linux-gnu</code> and <code>x86_64-apple-darwin</code> (platforms supported by <code>rules_rust</code>).
Process for moving a best effort platform to a supported platform is consensus-based.</p>
<h2>What are the stable APIs of <code>rules_rust</code>?</h2>
<p><code>//rust:defs.bzl</code> is subject to the backwards compatibility policy. That means
that anything directly accessible from this file is considered stable.</p>
<p><code>//rust/private/…</code> is not subject to the backwards compatibility policy. Content
of this package is an implementation detail.</p>
<p><code>//cargo:cargo_build_script.bzl</code> is subject to the backwards compatibility policy.</p>
<p><code>//cargo</code>, <code>//util</code>, <code>//tools</code>, <code>//test</code>, <code>//examples</code>, <code>//bindgen</code>, <code>//proto</code>,
<code>//wasm_bindgen</code> and any packages not mentioned by this document are by default
not subject to the backwards compatibility policy.</p>
<p>Experimental build settings are not subject to the backward compatibility
policy. They should be added to <code>//rust:experimental.bzl</code>.</p>
<p>Incompatible build settings are subject to the backward compatibility policy,
meaning the behavior of the flag cannot change in a backwards incompatible way.
They should be added to <code>//rust:incompatible.bzl</code>.</p>
<p>Bug fixes are not a breaking change by default. We'll use Common Sense (and we
will pull in more maintainers and the community to discuss) if we see a certain
bug fix is controversial. Incompatible changes to
<code>//cargo:cargo_build_script.bzl</code> that make <code>cargo_build_script</code> more accurately
follow cargo's behaviour are considered bug fixes.</p>
<h2>How to make a backwards incompatible change?</h2>
<ol>
<li>Create a GitHub issue (example:
<a href="https://github.com/bazelbuild/rules_rust/issues/591">Split rust_library into smaller rules#591</a>).</li>
<li>Describe the change, motivation for the change, provide migration
instructions/tooling.</li>
<li>Add a build setting into <code>//rust:incompatible.bzl</code> that removes the old
behavior (whenever possible) or changes the current behavior (when just
removing the old behavior is not possible). Ideally, users should not need to
manually flip incompatible flags.</li>
<li>Mention the link to the GitHub issue in error messages. Do not add a
deprecation warning (warnings make the deprecation visible to every user
building a project, not only to the maintainers of the project or the rules).</li>
<li>Mention the issue in the <code>CHANGELOG</code> file.</li>
<li>Give the community 3 months from the first release mentioning the issue until
the flag flip to migrate.</li>
</ol>
</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>`rules_rust` backwards compatibility policy</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">This document defines the backwards compatibility policy for rules_rust and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">defines the process for making compatibility breaking changes. Any exception to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">this process will have to be thoroughly discussed and there will have to be a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">consensus between maintainers that the exception should be granted.</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> <a-tt>What is a compatibility breaking change?</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text"></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 backwards compatible change has the property that a build that is green,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">correct, is using stable APIs of `rules_rust`, and is using a supported version</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">of Bazel before the change is still green and correct after the change. In</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">practice it means that users should not have to modify their project source</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">files, their `BUILD` files, their `bzl` files, their `rust_toolchain`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">definitions, their platform definitions, or their build settings.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></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 backwards compatible release has the property that it only contains backward</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text">compatible changes.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">`rules_rust` follow [SemVer 2.0.0](https://semver.org/). `rules_rust` promise</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">that all minor version number and patch version number releases only contain</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">backwards compatible changes.</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">`rules_rust` don&#39;t make any guarantees about compatibility between a released</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">version and the state of the `rules_rust` at HEAD.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">Backwards incompatible changes will have to follow a process in order to be</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">released. Users will be given at least one release where the old behavior is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">still present but deprecated to allow smooth migration of their project to the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">new behavior.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"></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> <a-tt>Compatibility before 1.0</a-tt></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">All minor version number releases before version 1.0 can be backwards incompatible.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text">Backwards incompatible changes still have to follow the the process, but minimum</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">time for migration is reduced to 2 weeks.</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-tt>What Bazel versions are supported?</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text">`rules_rust` support the current Bazel LTS at the time of a `rules_rust`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text">release.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text">Support for the current Bazel rolling release is on the best effort basis. If</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text">the CI build of `rules_rust` against the current Bazel rolling release is green,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text">it has to stay green. If the build is already red (because the new Bazel rolling</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text">release had incompatible changes that broke `rules_rust`), it is acceptable to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text">merge PRs leaving the build red as long as the reason for failure remains the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">same. We hope red CI with the current rolling release will be rare.</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">`rules_rust` don&#39;t promise all new `rules_rust` features available to the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text">current Bazel rolling release to be be available to the current Bazel LTS</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text">release (because Bazel compatibility policy doesn&#39;t allow us to make that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">promise, and some new features of `rules_rust` require new Bazel features that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text">are only available in Bazel rolling releases). `rules_rust` will aim that new</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text">features available to the current Bazel rolling release will be available to the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">next Bazel LTS release at latest.</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">Whenever there is a new Bazel LTS release, all releases of `rules_rust` will maintain</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text">support for the older LTS version for at least 3 months unless Bazel doesn&#39;t allow this.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>##</a-p> <a-tt>What host platforms are supported?</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text">Platforms subject to backwards compatibility policy are</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text">`x86_64-unknown-linux-gnu` and `x86_64-apple-darwin` (platforms supported by `rules_rust`).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text">Process for moving a best effort platform to a supported platform is consensus-based.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"></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>##</a-p> <a-tt>What are the stable APIs of `rules_rust`?</a-tt></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">`//rust:defs.bzl` is subject to the backwards compatibility policy. That means</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text">that anything directly accessible from this file is considered stable.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text">`//rust/private/…` is not subject to the backwards compatibility policy. Content</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text">of this package is an implementation detail.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text">`//cargo:cargo_build_script.bzl` is subject to the backwards compatibility policy.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text">`//cargo`, `//util`, `//tools`, `//test`, `//examples`, `//bindgen`, `//proto`,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text">`//wasm_bindgen` and any packages not mentioned by this document are by default</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text">not subject to the backwards compatibility policy.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text">Experimental build settings are not subject to the backward compatibility</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text">policy. They should be added to `//rust:experimental.bzl`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text">Incompatible build settings are subject to the backward compatibility policy,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text">meaning the behavior of the flag cannot change in a backwards incompatible way.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text">They should be added to `//rust:incompatible.bzl`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text">Bug fixes are not a breaking change by default. We&#39;ll use Common Sense (and we</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text">will pull in more maintainers and the community to discuss) if we see a certain</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text">bug fix is controversial. Incompatible changes to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text">`//cargo:cargo_build_script.bzl` that make `cargo_build_script` more accurately</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text">follow cargo&#39;s behaviour are considered bug fixes.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"><a-p>##</a-p> <a-tt>How to make a backwards incompatible change?</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"><a-p>1. </a-p>Create a GitHub issue (example:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text">[Split rust_library into smaller rules#591](https://github.com/bazelbuild/rules_rust/issues/591)).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text"><a-p>2. </a-p>Describe the change, motivation for the change, provide migration</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text">instructions/tooling.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text"><a-p>3. </a-p>Add a build setting into `//rust:incompatible.bzl` that removes the old</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text">behavior (whenever possible) or changes the current behavior (when just</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text">removing the old behavior is not possible). Ideally, users should not need to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text">manually flip incompatible flags.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"><a-p>4. </a-p>Mention the link to the GitHub issue in error messages. Do not add a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text">deprecation warning (warnings make the deprecation visible to every user</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text">building a project, not only to the maintainers of the project or the rules).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"><a-p>5. </a-p>Mention the issue in the `CHANGELOG` file.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"><a-p>6. </a-p>Give the community 3 months from the first release mentioning the issue until</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text">the flag flip to migrate.</span></span></pre></div></div>
</main>
</body>
</html>
