deploy: 5a440a1

_sources/community/developers/new_releases.md.txt

@@ -12,6 +12,7 @@ The `X`, `Y`, and `Z` values should be integers corresponding to the new version
 Releases will be made ad-hoc as bug-fixes and new features become available.
 When releasing a new version of a BrainGlobe repository, we also need to update the website, the metapackage, and any other tools that depend on that repository accordingly.
 This means we will typically create at least three dependent PRs;
+
 - One in the repository itself (containing the bugfix or new feature we'd like to release)
 - One in the [website repository](https://github.com/brainglobe/brainglobe.github.io) (to update documentation if necessary)
 - One for each repository that depends on the updated tool, to bump the dependency version
@@ -21,6 +22,31 @@ We should cross-link the latter to the website update, and release all affected
 Ideally, updates and releases should be made in an order that [follows the dependency tree](<project:repositories/brainglobe-meta/index.md#dependency-tree>) - starting with our lower level tools, than their dependents, then dependents of those dependents, and so on.
 The meta-package itself will always be the last by this convention.
 
+### Example, highlighting pinning from below
+
+It should be noted that our convention is to pin all our dependencies from below.
+This allows us to minimise the number of new releases we have to make when updating one of our tools that several others depend on.
+As such, when a package has a new release, only tools that depend on that package *that rely on the new features / structure* need to receive their own version bump (and thus a PR in the chain described above).
+
+For example, suppose we have package `BG-A` at version `v1.0.0` which provides three features; `F1.foo`, `F1.bar`, and `F2`.
+Then we have packages:
+
+- `BG-B`, version `v1.2.0`, that uses `F1.foo`,
+- `BG-C`, version `v1.5.0`, that uses `F1.bar`,
+- `BG-D`, version `v1.7.0`, that uses `F2`.
+
+Let's pretend that update `v1.1.0` to `BG-A` is going to re-write `F1.foo` to be more efficient (but keep the name), move `F1.bar` to `F2.bar`, and not change `F2`.
+In this case, the PR chain would consist of:
+
+- `BG-B` needs a new version (say `v1.2.1`), with the `BG-A` dependency pinned to `>=1.1.0`. This is so that the new `F1.foo` is used when `BG-A` is fetched by pip/conda.
+- `BG-C` needs a new version (say `v1.6.0`), with the `BG-A` dependency pinned to `>=1.1.0` too. This is because version `v1.1.0` of `BG-A` is incompatible with `v1.0.0`. If we don't release a new `BG-C` version with this change, a user could `pip install BG-C`, have `BG-A` `v1.1.0` fetched as part of the dependency resolution, then would encounter an error whenever they tried to use `BG-C` since `F1.bar` would be unavailable (it's now `F2.bar`).
+- `BG-D` doesn't need any new releases, since `F2` has not been affected by the `v1.1.0` update to `BG-A`.
+- The metapackage then needs a new version which pins:
+  - `BG-A >= v1.1.0`
+  - `BG-B >= v1.2.1`
+  - `BG-C >= v1.6.0`
+  - `BG-D >= v1.7.0` (no change)
+
 ## Triggering a new release
 
 The steps for triggering a new release are:
@@ -55,7 +81,7 @@ if you want to annotate the tag; which is useful for tagging single-commit hotfi
 
 Once you have created the tag, you can `git push --tags` back to the main repository to trigger the release workflow.
 **However** you still need to create release notes using the GitHub UI as described in [the section above](#triggering-a-new-release).
-You will need to select the tag you just pushed, rather than creating a new tag, when you start drafting the release notes. 
+You will need to select the tag you just pushed, rather than creating a new tag, when you start drafting the release notes.
 
 ### Failed workflows
 
@@ -71,11 +97,10 @@ In the event that the release workflows fails after publishing a release, you wi
 A number of BrainGlobe packages are also available through `conda-forge`, providing an alternative installation method to `pip`.
 Each package available in this way has a feedstock repository, usually at the GitHub repository:
 
-```
+```sh
 conda-forge/<package-name>-feedstock
 ```
 
-
 These feedstocks are linked to their `PyPI` counterparts - when a new version comes available on `PyPI`, the `conda-forge` admin bot should open a PR in the feedstock repository which will update the version of the package available through `conda`.
 These PRs must be approved by one of the feedstock maintainers before they are merged in.
 
@@ -95,5 +120,5 @@ The basic functionality of these workflows use the [neuroinformatics-unit](https
 1. Check the package manifest
 1. Run the package tests
 
-These checks are run against _all_ PRs opened against the repository, and on the `main` branch when they are merged in.
-When a tag in the `vX.Y.Z` format is pushed to `main`, these checks are run again and _if they are successful_ the workflow will build the source distribution and upload this to `PyPI`.
+These checks are run against *all* PRs opened against the repository, and on the `main` branch when they are merged in.
+When a tag in the `vX.Y.Z` format is pushed to `main`, these checks are run again and *if they are successful* the workflow will build the source distribution and upload this to `PyPI`.

community/developers/new_releases.html

@@ -613,6 +613,34 @@ <h2>Coordinating releases with the documentation and the metapackage<a class="he
 <p>We should cross-link the latter to the website update, and release all affected packages to PyPI (and conda if appropriate) once they are all merged into <code class="docutils literal notranslate"><span class="pre">main</span></code>.
 Ideally, updates and releases should be made in an order that <a class="reference internal" href="repositories/brainglobe-meta/index.html#id1"><span class="std std-ref">follows the dependency tree</span></a> - starting with our lower level tools, than their dependents, then dependents of those dependents, and so on.
 The meta-package itself will always be the last by this convention.</p>
+<section id="example-highlighting-pinning-from-below">
+<h3>Example, highlighting pinning from below<a class="headerlink" href="#example-highlighting-pinning-from-below" title="Link to this heading">#</a></h3>
+<p>It should be noted that our convention is to pin all our dependencies from below.
+This allows us to minimise the number of new releases we have to make when updating one of our tools that several others depend on.
+As such, when a package has a new release, only tools that depend on that package <em>that rely on the new features / structure</em> need to receive their own version bump (and thus a PR in the chain described above).</p>
+<p>For example, suppose we have package <code class="docutils literal notranslate"><span class="pre">BG-A</span></code> at version <code class="docutils literal notranslate"><span class="pre">v1.0.0</span></code> which provides three features; <code class="docutils literal notranslate"><span class="pre">F1.foo</span></code>, <code class="docutils literal notranslate"><span class="pre">F1.bar</span></code>, and <code class="docutils literal notranslate"><span class="pre">F2</span></code>.
+Then we have packages:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">BG-B</span></code>, version <code class="docutils literal notranslate"><span class="pre">v1.2.0</span></code>, that uses <code class="docutils literal notranslate"><span class="pre">F1.foo</span></code>,</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">BG-C</span></code>, version <code class="docutils literal notranslate"><span class="pre">v1.5.0</span></code>, that uses <code class="docutils literal notranslate"><span class="pre">F1.bar</span></code>,</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">BG-D</span></code>, version <code class="docutils literal notranslate"><span class="pre">v1.7.0</span></code>, that uses <code class="docutils literal notranslate"><span class="pre">F2</span></code>.</p></li>
+</ul>
+<p>Let’s pretend that update <code class="docutils literal notranslate"><span class="pre">v1.1.0</span></code> to <code class="docutils literal notranslate"><span class="pre">BG-A</span></code> is going to re-write <code class="docutils literal notranslate"><span class="pre">F1.foo</span></code> to be more efficient (but keep the name), move <code class="docutils literal notranslate"><span class="pre">F1.bar</span></code> to <code class="docutils literal notranslate"><span class="pre">F2.bar</span></code>, and not change <code class="docutils literal notranslate"><span class="pre">F2</span></code>.
+In this case, the PR chain would consist of:</p>
+<ul class="simple">
+<li><p><code class="docutils literal notranslate"><span class="pre">BG-B</span></code> needs a new version (say <code class="docutils literal notranslate"><span class="pre">v1.2.1</span></code>), with the <code class="docutils literal notranslate"><span class="pre">BG-A</span></code> dependency pinned to <code class="docutils literal notranslate"><span class="pre">&gt;=1.1.0</span></code>. This is so that the new <code class="docutils literal notranslate"><span class="pre">F1.foo</span></code> is used when <code class="docutils literal notranslate"><span class="pre">BG-A</span></code> is fetched by pip/conda.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">BG-C</span></code> needs a new version (say <code class="docutils literal notranslate"><span class="pre">v1.6.0</span></code>), with the <code class="docutils literal notranslate"><span class="pre">BG-A</span></code> dependency pinned to <code class="docutils literal notranslate"><span class="pre">&gt;=1.1.0</span></code> too. This is because version <code class="docutils literal notranslate"><span class="pre">v1.1.0</span></code> of <code class="docutils literal notranslate"><span class="pre">BG-A</span></code> is incompatible with <code class="docutils literal notranslate"><span class="pre">v1.0.0</span></code>. If we don’t release a new <code class="docutils literal notranslate"><span class="pre">BG-C</span></code> version with this change, a user could <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">BG-C</span></code>, have <code class="docutils literal notranslate"><span class="pre">BG-A</span></code> <code class="docutils literal notranslate"><span class="pre">v1.1.0</span></code> fetched as part of the dependency resolution, then would encounter an error whenever they tried to use <code class="docutils literal notranslate"><span class="pre">BG-C</span></code> since <code class="docutils literal notranslate"><span class="pre">F1.bar</span></code> would be unavailable (it’s now <code class="docutils literal notranslate"><span class="pre">F2.bar</span></code>).</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">BG-D</span></code> doesn’t need any new releases, since <code class="docutils literal notranslate"><span class="pre">F2</span></code> has not been affected by the <code class="docutils literal notranslate"><span class="pre">v1.1.0</span></code> update to <code class="docutils literal notranslate"><span class="pre">BG-A</span></code>.</p></li>
+<li><p>The metapackage then needs a new version which pins:</p>
+<ul>
+<li><p><code class="docutils literal notranslate"><span class="pre">BG-A</span> <span class="pre">&gt;=</span> <span class="pre">v1.1.0</span></code></p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">BG-B</span> <span class="pre">&gt;=</span> <span class="pre">v1.2.1</span></code></p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">BG-C</span> <span class="pre">&gt;=</span> <span class="pre">v1.6.0</span></code></p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">BG-D</span> <span class="pre">&gt;=</span> <span class="pre">v1.7.0</span></code> (no change)</p></li>
+</ul>
+</li>
+</ul>
+</section>
 </section>
 <section id="triggering-a-new-release">
 <h2>Triggering a new release<a class="headerlink" href="#triggering-a-new-release" title="Link to this heading">#</a></h2>
@@ -658,7 +686,7 @@ <h3>Failed workflows<a class="headerlink" href="#failed-workflows" title="Link t
 <h3><code class="docutils literal notranslate"><span class="pre">conda-forge</span></code> feedstocks<a class="headerlink" href="#conda-forge-feedstocks" title="Link to this heading">#</a></h3>
 <p>A number of BrainGlobe packages are also available through <code class="docutils literal notranslate"><span class="pre">conda-forge</span></code>, providing an alternative installation method to <code class="docutils literal notranslate"><span class="pre">pip</span></code>.
 Each package available in this way has a feedstock repository, usually at the GitHub repository:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span><span class="o">-</span><span class="n">forge</span><span class="o">/&lt;</span><span class="n">package</span><span class="o">-</span><span class="n">name</span><span class="o">&gt;-</span><span class="n">feedstock</span>
+<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>conda-forge/&lt;package-name&gt;-feedstock
 </pre></div>
 </div>
 <p>These feedstocks are linked to their <code class="docutils literal notranslate"><span class="pre">PyPI</span></code> counterparts - when a new version comes available on <code class="docutils literal notranslate"><span class="pre">PyPI</span></code>, the <code class="docutils literal notranslate"><span class="pre">conda-forge</span></code> admin bot should open a PR in the feedstock repository which will update the version of the package available through <code class="docutils literal notranslate"><span class="pre">conda</span></code>.
@@ -736,7 +764,10 @@ <h2>Workflow for publishing new releases<a class="headerlink" href="#workflow-fo
   </div>
   <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
     <ul class="visible nav section-nav flex-column">
-<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#coordinating-releases-with-the-documentation-and-the-metapackage">Coordinating releases with the documentation and the metapackage</a></li>
+<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#coordinating-releases-with-the-documentation-and-the-metapackage">Coordinating releases with the documentation and the metapackage</a><ul class="nav section-nav flex-column">
+<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#example-highlighting-pinning-from-below">Example, highlighting pinning from below</a></li>
+</ul>
+</li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#triggering-a-new-release">Triggering a new release</a><ul class="nav section-nav flex-column">
 <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#on-the-command-line">On the command line</a></li>
 <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#failed-workflows">Failed workflows</a></li>