You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: _sources/community/developers/new_releases.md.txt
+30-5
Original file line number
Diff line number
Diff line change
@@ -12,6 +12,7 @@ The `X`, `Y`, and `Z` values should be integers corresponding to the new version
12
12
Releases will be made ad-hoc as bug-fixes and new features become available.
13
13
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.
14
14
This means we will typically create at least three dependent PRs;
15
+
15
16
- One in the repository itself (containing the bugfix or new feature we'd like to release)
16
17
- One in the [website repository](https://github.com/brainglobe/brainglobe.github.io) (to update documentation if necessary)
17
18
- 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
21
22
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.
22
23
The meta-package itself will always be the last by this convention.
23
24
25
+
### Example, highlighting pinning from below
26
+
27
+
It should be noted that our convention is to pin all our dependencies from below.
28
+
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.
29
+
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).
30
+
31
+
For example, suppose we have package `BG-A` at version `v1.0.0` which provides three features; `F1.foo`, `F1.bar`, and `F2`.
32
+
Then we have packages:
33
+
34
+
- `BG-B`, version `v1.2.0`, that uses `F1.foo`,
35
+
- `BG-C`, version `v1.5.0`, that uses `F1.bar`,
36
+
- `BG-D`, version `v1.7.0`, that uses `F2`.
37
+
38
+
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`.
39
+
In this case, the PR chain would consist of:
40
+
41
+
- `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.
42
+
- `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`).
43
+
- `BG-D` doesn't need any new releases, since `F2` has not been affected by the `v1.1.0` update to `BG-A`.
44
+
- The metapackage then needs a new version which pins:
45
+
- `BG-A >= v1.1.0`
46
+
- `BG-B >= v1.2.1`
47
+
- `BG-C >= v1.6.0`
48
+
- `BG-D >= v1.7.0` (no change)
49
+
24
50
## Triggering a new release
25
51
26
52
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
55
81
56
82
Once you have created the tag, you can `git push --tags` back to the main repository to trigger the release workflow.
57
83
**However** you still need to create release notes using the GitHub UI as described in [the section above](#triggering-a-new-release).
58
-
You will need to select the tag you just pushed, rather than creating a new tag, when you start drafting the release notes.
84
+
You will need to select the tag you just pushed, rather than creating a new tag, when you start drafting the release notes.
59
85
60
86
### Failed workflows
61
87
@@ -71,11 +97,10 @@ In the event that the release workflows fails after publishing a release, you wi
71
97
A number of BrainGlobe packages are also available through `conda-forge`, providing an alternative installation method to `pip`.
72
98
Each package available in this way has a feedstock repository, usually at the GitHub repository:
73
99
74
-
```
100
+
```sh
75
101
conda-forge/<package-name>-feedstock
76
102
```
77
103
78
-
79
104
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`.
80
105
These PRs must be approved by one of the feedstock maintainers before they are merged in.
81
106
@@ -95,5 +120,5 @@ The basic functionality of these workflows use the [neuroinformatics-unit](https
95
120
1. Check the package manifest
96
121
1. Run the package tests
97
122
98
-
These checks are run against _all_ PRs opened against the repository, and on the `main` branch when they are merged in.
99
-
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`.
123
+
These checks are run against *all* PRs opened against the repository, and on the `main` branch when they are merged in.
124
+
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`.
Copy file name to clipboardexpand all lines: community/developers/new_releases.html
+33-2
Original file line number
Diff line number
Diff line change
@@ -613,6 +613,34 @@ <h2>Coordinating releases with the documentation and the metapackage<a class="he
613
613
<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 <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code>.
614
614
Ideally, updates and releases should be made in an order that <aclass="reference internal" href="repositories/brainglobe-meta/index.html#id1"><spanclass="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.
615
615
The meta-package itself will always be the last by this convention.</p>
<h3>Example, highlighting pinning from below<aclass="headerlink" href="#example-highlighting-pinning-from-below" title="Link to this heading">#</a></h3>
618
+
<p>It should be noted that our convention is to pin all our dependencies from below.
619
+
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.
620
+
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>
621
+
<p>For example, suppose we have package <codeclass="docutils literal notranslate"><spanclass="pre">BG-A</span></code> at version <codeclass="docutils literal notranslate"><spanclass="pre">v1.0.0</span></code> which provides three features; <codeclass="docutils literal notranslate"><spanclass="pre">F1.foo</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">F1.bar</span></code>, and <codeclass="docutils literal notranslate"><spanclass="pre">F2</span></code>.
622
+
Then we have packages:</p>
623
+
<ulclass="simple">
624
+
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">BG-B</span></code>, version <codeclass="docutils literal notranslate"><spanclass="pre">v1.2.0</span></code>, that uses <codeclass="docutils literal notranslate"><spanclass="pre">F1.foo</span></code>,</p></li>
625
+
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">BG-C</span></code>, version <codeclass="docutils literal notranslate"><spanclass="pre">v1.5.0</span></code>, that uses <codeclass="docutils literal notranslate"><spanclass="pre">F1.bar</span></code>,</p></li>
626
+
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">BG-D</span></code>, version <codeclass="docutils literal notranslate"><spanclass="pre">v1.7.0</span></code>, that uses <codeclass="docutils literal notranslate"><spanclass="pre">F2</span></code>.</p></li>
627
+
</ul>
628
+
<p>Let’s pretend that update <codeclass="docutils literal notranslate"><spanclass="pre">v1.1.0</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">BG-A</span></code> is going to re-write <codeclass="docutils literal notranslate"><spanclass="pre">F1.foo</span></code> to be more efficient (but keep the name), move <codeclass="docutils literal notranslate"><spanclass="pre">F1.bar</span></code> to <codeclass="docutils literal notranslate"><spanclass="pre">F2.bar</span></code>, and not change <codeclass="docutils literal notranslate"><spanclass="pre">F2</span></code>.
629
+
In this case, the PR chain would consist of:</p>
630
+
<ulclass="simple">
631
+
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">BG-B</span></code> needs a new version (say <codeclass="docutils literal notranslate"><spanclass="pre">v1.2.1</span></code>), with the <codeclass="docutils literal notranslate"><spanclass="pre">BG-A</span></code> dependency pinned to <codeclass="docutils literal notranslate"><spanclass="pre">>=1.1.0</span></code>. This is so that the new <codeclass="docutils literal notranslate"><spanclass="pre">F1.foo</span></code> is used when <codeclass="docutils literal notranslate"><spanclass="pre">BG-A</span></code> is fetched by pip/conda.</p></li>
632
+
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">BG-C</span></code> needs a new version (say <codeclass="docutils literal notranslate"><spanclass="pre">v1.6.0</span></code>), with the <codeclass="docutils literal notranslate"><spanclass="pre">BG-A</span></code> dependency pinned to <codeclass="docutils literal notranslate"><spanclass="pre">>=1.1.0</span></code> too. This is because version <codeclass="docutils literal notranslate"><spanclass="pre">v1.1.0</span></code> of <codeclass="docutils literal notranslate"><spanclass="pre">BG-A</span></code> is incompatible with <codeclass="docutils literal notranslate"><spanclass="pre">v1.0.0</span></code>. If we don’t release a new <codeclass="docutils literal notranslate"><spanclass="pre">BG-C</span></code> version with this change, a user could <codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre">BG-C</span></code>, have <codeclass="docutils literal notranslate"><spanclass="pre">BG-A</span></code><codeclass="docutils literal notranslate"><spanclass="pre">v1.1.0</span></code> fetched as part of the dependency resolution, then would encounter an error whenever they tried to use <codeclass="docutils literal notranslate"><spanclass="pre">BG-C</span></code> since <codeclass="docutils literal notranslate"><spanclass="pre">F1.bar</span></code> would be unavailable (it’s now <codeclass="docutils literal notranslate"><spanclass="pre">F2.bar</span></code>).</p></li>
633
+
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">BG-D</span></code> doesn’t need any new releases, since <codeclass="docutils literal notranslate"><spanclass="pre">F2</span></code> has not been affected by the <codeclass="docutils literal notranslate"><spanclass="pre">v1.1.0</span></code> update to <codeclass="docutils literal notranslate"><spanclass="pre">BG-A</span></code>.</p></li>
634
+
<li><p>The metapackage then needs a new version which pins:</p>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">BG-D</span><spanclass="pre">>=</span><spanclass="pre">v1.7.0</span></code> (no change)</p></li>
640
+
</ul>
641
+
</li>
642
+
</ul>
643
+
</section>
616
644
</section>
617
645
<sectionid="triggering-a-new-release">
618
646
<h2>Triggering a new release<aclass="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
658
686
<h3><codeclass="docutils literal notranslate"><spanclass="pre">conda-forge</span></code> feedstocks<aclass="headerlink" href="#conda-forge-feedstocks" title="Link to this heading">#</a></h3>
659
687
<p>A number of BrainGlobe packages are also available through <codeclass="docutils literal notranslate"><spanclass="pre">conda-forge</span></code>, providing an alternative installation method to <codeclass="docutils literal notranslate"><spanclass="pre">pip</span></code>.
660
688
Each package available in this way has a feedstock repository, usually at the GitHub repository:</p>
<p>These feedstocks are linked to their <codeclass="docutils literal notranslate"><spanclass="pre">PyPI</span></code> counterparts - when a new version comes available on <codeclass="docutils literal notranslate"><spanclass="pre">PyPI</span></code>, the <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">conda</span></code>.
@@ -736,7 +764,10 @@ <h2>Workflow for publishing new releases<a class="headerlink" href="#workflow-fo
<liclass="toc-h2 nav-item toc-entry"><aclass="reference internal nav-link" href="#coordinating-releases-with-the-documentation-and-the-metapackage">Coordinating releases with the documentation and the metapackage</a></li>
767
+
<liclass="toc-h2 nav-item toc-entry"><aclass="reference internal nav-link" href="#coordinating-releases-with-the-documentation-and-the-metapackage">Coordinating releases with the documentation and the metapackage</a><ulclass="nav section-nav flex-column">
768
+
<liclass="toc-h3 nav-item toc-entry"><aclass="reference internal nav-link" href="#example-highlighting-pinning-from-below">Example, highlighting pinning from below</a></li>
769
+
</ul>
770
+
</li>
740
771
<liclass="toc-h2 nav-item toc-entry"><aclass="reference internal nav-link" href="#triggering-a-new-release">Triggering a new release</a><ulclass="nav section-nav flex-column">
741
772
<liclass="toc-h3 nav-item toc-entry"><aclass="reference internal nav-link" href="#on-the-command-line">On the command line</a></li>
0 commit comments