V1 updates for brainreg changes

docs/source/blog/version1/brainreg_update_live.md

@@ -0,0 +1,35 @@
+---
+blogpost: true
+date: Nov 1, 2023
+author: Will Graham
+location: London, England
+category: BrainGlobe-v1
+language: English
+---
+
+# Version 1 of `brainreg` and `brainglobe-segmentation` released
+
+The [restructuring of BrainGlobe](./version_1_announcement.md) is underway, beginning with the release of version 1 of `brainreg` and `brainglobe-segmentation` (previously known as `brainreg-segment`).
+Previously, there were three tools with the prefix `brainreg` ("brain registration") that were split across three packages:
+
+- `brainreg` was the core Python package that contained the functional code for performing registration of an atlas to a sample image (sequence).
+- `brainreg-napari` provided a plugin to perform the registration steps interactively through napari. It depended on `brainreg` for the core functionality.
+- `brainreg-segment` was a companion to `brainreg` that allowed for manual segmentation of regions/objects within the brain. However it was not necessarily involved with the registration process itself.
+
+This release sees `brainreg` come bundled with its napari plugin as an optional package extra, rather than requiring users to install the two packages separately.
+Consequentially, `brainreg-napari` has been retired; we recommend you uninstall this package from your environments when you update.
+The "combined" `brainreg` is now tagged as `brainreg v1.0.0` and should be considered a stable first release of this tool.
+
+`brainglobe-segmentation` is the new name of the `brainreg-segment` tool.
+With the forthcoming release of BrainGlobe version 1 and the development of `brainglobe-registration`, the decision was made to disambiguate the role of the segmentation functionality and combine the napari plugin with the core functionality.
+
+## What do I need to do?
+
+If you were previously using any of the affected tools; you don't need to do anything right now if you want to wait for the full release of BrainGlobe version 1, which will take care of these dependencies for you.
+In the time between now and then, the tools as installed will still work but be aware that they will no longer receive updates due to the restructuring.
+
+If you would like to update your packages now, or would like to know how this will affect your scripts or workflows, [see the full changelog](#full-changelog) which covers API changes and the installation process.
+
+## Full changelog
+
+You can find the [full changelog on the releases page](../../releases/v1/brainreg.md).

docs/source/index.md

@@ -39,6 +39,14 @@ How do I get started with these tools?
 Find out more about these tools.
 :::
 
+:::{grid-item-card} {fas}`tags;sd-text-primary` Releases
+:img-bottom: _static/atlases.png
+:link: releases/index
+:link-type: doc
+
+Release notes and changelogs.
+:::
+
 ::::
 
 ```{toctree}
@@ -48,6 +56,7 @@ Find out more about these tools.
 about
 tutorials/index
 documentation/index
+releases/index
 blog/index
 more
 ```

docs/source/releases/index.md

@@ -0,0 +1,11 @@
+# Releases
+
+Changelogs and release notes for all BrainGlobe tools, all in one place.
+
+## BrainGlobe restructuring (version 1) release notes
+
+```{toctree}
+:maxdepth: 2
+
+v1/index
+```

docs/source/releases/v1/brainreg.md

@@ -0,0 +1,60 @@
+# Version 1: changes to registration and segmentation tools
+
+## `brainreg` and `brainreg-napari`
+
+The previously separate packages `brainreg` and `brainreg-napari` have now been combined into a single package that keeps the `brainreg` name.
+This (new) `brainreg` package contains two submodules; `brainreg.core` whose contents are equivalent to the (old) `brainreg` package, and `brainreg.napari` that handles the napari widget.
+The `brainreg.napari` module is optional and needs to be specified at install if you are not intending to install it via the BrainGlobe version 1 package.
+
+If you were previously using brainreg in your scripts and have updated to version 1, you will now need to use `brainreg.core` instead of `brainreg`.
+However, the internal structure of the `core` submodule has been retained, so updating your scripts should be a case of replacing "`brainreg`" with "`brainreg.core`" across your codebase.
+Similarly, if you were ever importing `brainreg_napari` into your Python scripts, you will need to replace all occurrences of this with `brainreg.napari`.
+
+If you are installing `brainreg` as part of the brainglobe version 1 package, the napari plugin will be automatically included and you won't need to do anything else to install the plugin.
+Otherwise, to install the napari plugin, you will need to install `brainreg` with it's optional napari dependency via pip (recommended)
+
+```bash
+python -m pip install brainreg[napari]
+```
+
+or alternatively via conda
+
+```bash
+conda install brainreg
+```
+
+After updating, you may want to remove the now deprecated `brainreg-napari` package from your environment if it still persists;
+
+```bash
+pip uninstall brainreg-napari # If you originally installed via pip
+conda remove brainreg-napari # If you originally installed via conda
+```
+
+## Command-line executable
+
+The command-line executable has retained the name `brainreg` and has undergone no usability changes.
+
+## napari plugin
+
+When loading the plugin in napari, you will now find it listed under the plugins menu as "`Atlas Registration (brainreg)`" rather than "`Atlas Registration (brainreg-napari)`".
+If you have external scripts that reply on the internal name of the plugin, you will need to update these to `brainreg` (from `brainreg-napari`) accordingly.
+
+## `brainreg-segment`
+
+This package has been renamed `brainglobe-segmentation`.
+Beyond this renaming, there have been no internal changes to the package, so you may continue to use it as previously.
+However, you will need to switch all occurrences of `brainglobe_segment` to `brainglobe_segmentation` in your Python scripts.
+
+If you want to install the package standalone (without using BrainGlobe version 1 or through installing `brainreg`) then we recommend you `pip install` the package into your environment:
+
+```bash
+pip install brainglobe-segmentation
+```
+
+If you have `brainreg-segment` in your environment, you may wish to remove it as it will no longer be needed by `brainreg`:
+
+```bash
+pip uninstall brainreg-segment
+```
+
+however, `brainreg-segment` is still required by [`cellfinder`](../../documentation/cellfinder/index.md) versions `<=v1.0.0`.

docs/source/releases/v1/index.md

@@ -0,0 +1,20 @@
+# BrainGlobe version 1 overview
+
+## Changes at-a-glance
+
+Below is a high-level overview of the changes to the brainglobe suite of tools that we offer.
+You can follow the links provided for more information; including a listing of relocated and/or renamed tools.
+
+| Change |   |
+|--------|:-:|
+brainreg and brainreg-napari have been merged into a single package | [Further info](./brainreg.md#brainreg-and-brainreg-napari) |
+brainreg-segment has been renamed to brainglobe-segmentation | [Further info](./brainreg.md#brainreg-segment) |
+
+## Complete index
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+brainreg
+```