Version 1 release

docs/source/blog/version1/version_1_released.md

@@ -0,0 +1,68 @@
+---
+blogpost: true
+date: Jan 8th, 2024
+author: Will Graham
+location: London, England
+category: BrainGlobe-v1
+language: English
+---
+
+# BrainGlobe version 1 is here! :partying_face:
+
+Following our series of incremental updates to a number of BrainGlobe tools, we are pleased to announce that BrainGlobe version 1 has been released today!
+Users can now enjoy:
+
+- A one-line installation of _all_ BrainGlobe tools, automatically handling dependency inconsistencies and providing the _entire_ BrainGlobe tool suite. Individual tools no longer need to be manually installed as-and-when they're needed, and users do not need to worry about the behind-the-scenes organisation of the packages providing the tools.
+- A clearer and more consistent naming convention for the tools that are provided.
+- Access to example analysis workflows, installable on top of the BrainGlobe tool suite.
+
+BrainGlobe version 1 is hallmarked by the release of (version 1 of) the [`brainglobe` package on PyPI](https://pypi.org/project/brainglobe/), and the new [`brainglobe-workflows` package](https://pypi.org/project/brainglobe-workflows/).
+
+## Users: what you need to know
+
+The version 1 release of `brainglobe` on PyPI will provide you with the entire BrainGlobe tool suite and ensure that the tools are consistent with one another.
+You will no longer need to worry about manually installing individual BrainGlobe tools and checking how they interface with other tools.
+You can also easily install the complete BrainGlobe suite of tools on a new machine or into a fresh environment in a single `pip` command:
+
+```bash
+pip install brainglobe>=1.0.0
+```
+
+The `brainglobe` package, or "meta-package" as we like to refer to it, ensures that the BrainGlobe tools installed onto your machine are stable and consistent with each other.
+Key packages provided include:
+
+- `bg-atlasapi`
+- `brainreg`
+- `brainrender` and `brainrender-napari` (new with version 1)
+- `brainglobe-napari-io`
+- `brainglobe-segmentation`
+- `cellfinder`
+
+The individual tools that you have been using are still available, and are largely still using the same name (with the exception of the old `cellfinder` command-line-tool, see below).
+Regardless of how many of our tools you use in your analysis, we recommend that you create a new environment and (re)install any BrainGlobe tools you have been using following the instructions on the installation page.
+
+For the most part, the effects of moving to version 1 should be limited to the cases where a tool has been merged with its napari plugin, or the relocation of the (old) cellfinder command-line tool.
+The previous blog posts in this series outline these changes:
+
+- [Blog post](./brainreg_update_live.md) | `brainreg`, `brainreg-napari` have been merged, whilst the somewhat unrelated `brainreg-segment` package has been renamed to distinguish it.
+- [Blog post](./cellfinder_migration_live.md) | The old command-line tool (which confusingly was called "cellfinder" despite being a combination of several BrainGlobe tools) has been moved to `brainmapper` in the `brainglobe-workflows` package.
+- [Blog post](./core_and_napari_merge.md) | `cellfinder-core` and `cellfinder-napari` have been merged into just "`cellfinder`".
+
+Our vision for the new `brainglobe-workflows` package is to take this one step further and provide a selection of pre-written data analysis pipelines for neuroscientific data.
+Currently the `brainglobe-workflows` package contains the successor to the old cellfinder command-line tool, now called `brainmapper`, but additional workflows will be added in the future.
+
+## Developers: what you need to know
+
+The `brainglobe` package allows us to ensure that tools cannot be installed in a manner which is inconsistent with each other.
+If tool `A` necessitates a change in tool `B`, it was possible to update `A` without knowing about the knock-on effect on `B`, which would cause bugs further down the line.
+Now the `brainglobe` package can be re-released in a manner which pins consistent versions of `A` and `B`, preventing this from happening.
+
+The `brainglobe-workflows` package allows us to do two further things:
+
+- It provides a distinct location for workflows that utilise BrainGlobe tools, so these workflows are not bundled together with their backends.
+- It provides us with a set of analysis pipelines that we expect users to frequently run, which we can use to benchmark our tools and identify areas for improvement in terms of performance or speed.
+- It builds on top of the `brainglobe` package, rather than having packages be interdependent on each other due to a workflow utilising multiple tools but being provided with its backend.
+
+## Full Changelog
+
+The full changelog is [available here](/community/releases/v1/index.md).

docs/source/community/releases/v1/index.md

@@ -1,5 +1,24 @@
 # BrainGlobe version 1 overview
 
+BrainGlobe version 1 provides users with the `brainglobe` "meta"-package: a single package that will fetch all the tools in the BrainGlobe suite and install them onto your machine, ready for use.
+It also provides the `brainglobe-workflows` package, which builds on top of `brainglobe` and provides some common analysis pipelines to users, as well as a benchmarking suite for developers working on code performance improvements.
+
+## Updating to version 1
+
+Our recommendation for updating to BrainGlobe version 1 is to follow the [installation instructions on the main documentation page](/documentation/index.md#installing-brainglobe) in a clean virtual environment, and delete or archive your old environment.
+This will ensure that when you install `brainglobe`, the tools are fetched in a consistent manner and do not pick up any manually installed BrainGlobe tools that might be in your environment or python path.
+Likewise, it also avoids potential issues when tools have been installed from both `conda-forge` and `PyPI`.
+
+If you don't want to install the entire BrainGlobe suite and are happy to manage the tooling interdependencies yourself, you can still manually install the individual BrainGlobe tools that you wish to use.
+If you choose to do so; as a general rule of thumb you should not mix `conda-forge` and `PyPI` installs, and avoid installing BrainGlobe tools of versions less than 1 in the same environment as those with version greater than 1 at all costs.
+
+### Previous installs with conda
+
+If you have previously installed any of our tools from conda, we strongly recommend that you create a new environment and follow the `pip` installation instructions provided on the [installation page](/documentation/index.md#installing-brainglobe).
+The new "version 1" of BrainGlobe provides a PyPI package that comes with the complete suite of tools, and ensures that these are all consistent with one another.
+These are fetched by `pip` and so may cause conflicts if they are already present in your environment, having been fetched from `conda-forge`.
+Mixing `conda-forge` installed packages with the `brainglobe` package from PyPI will likely throw versioning issues as we can't guarantee that `conda` will resolve the tool dependencies correctly.
+
 ## Changes at-a-glance
 
 Below is a high-level overview of the changes to the brainglobe suite of tools that we offer.
@@ -13,8 +32,8 @@ The `cellfinder` command-line-interface has been moved into `brainglobe-workflow
 The cellfinder package is deprecated - it will later be recycled to merge some backend functionality | [Further info](cellfinder-migration.md#cellfinder-repository) |
 The cellfinder Docker image is discontinued | [Further info](cellfinder-migration.md#cellfinder-docker-image) |
 cellfinder-core and cellfinder-napari merged into "new cellfinder" | [Further info](cellfinder-core-and-plugin-merge.md) |
-
-## Complete index
+The cellfinder command-line tool has been replaced with `brainmapper` | [Further info](cellfinder-core-and-plugin-merge.md) |
+`brainrender` and `brainrender-napari` are now available through the `brainglobe` meta-package | [Further info](/blog/version1/version_1_released.md)
 
 ```{toctree}
 :maxdepth: 1
@@ -24,3 +43,32 @@ brainreg
 cellfinder-migration
 cellfinder-core-and-plugin-merge
 ```
+
+## Full Changelog
+
+- Recommended BrainGlobe install is via pip, into a clean environment.
+  - `pip install brainglobe` to install BrainGlobe tools. Recommended even if you only want to use one or two tools.
+  - `pip install brainglobe-workflows` if you also want to use the example analysis workflows that we provide.
+- `brainreg-napari` is now shipped with `brainreg`
+  - `brainreg` functionality is now available in a submodule, `brainreg.core`. If you previously used the Python API provided in `brainreg`, you will need to change your `from brainreg import X` statements to `from brainreg.core import X`.
+  - The `brainreg-napari` plugin is now just called `brainreg` when using `napari`. The plugin's backend is in the submodule `brainreg.napari` rather than `brainreg-napari`.
+  - The new `brainreg.core` and `brainreg.napari` submodules retain the old internal structure of the respective deprecated packages.
+- `brainreg-segment` has been renamed `brainglobe-segmentation`.
+  - Beyond the name change, package internals have not changed.
+- `cellfinder` command-line-interface (CLI) has been renamed and moved.
+  - The command-line interface is now provided by `brainglobe-workflows`.
+  - The command-line tool is now called `brainmapper`.
+  - The name "cellfinder" is now reserved for the merged `cellfinder-core` and `cellfinder-napari` packages.
+- `cellfinder-core` and `cellfinder-napari` have been merged into a single package, called `cellfinder`.
+  - The `cellfinder` package should not be confused with the old cellfinder command-line tool, described above. Going forward, "cellfinder" will refer exclusively to this new, merged package created from `cellfinder-core` and `cellfinder-napari`. The command-line tool with use the name `brianmapper`.
+  - The `core` and `napari` features are now available as submodules of the `cellfinder` package. If you previously used `from cellfinder_core import X`, you'll have to use `from cellfinder.core import X` instead.
+  - Internal function names and locations have otherwise not changed, beyond their conversion into the `core` and `napari` submodules.
+  - The napari plugin is now referred to as the `cellfinder` plugin, and shows up with the name `cellfinder` when viewed in napari (as opposed to the old `cellfinder-napari` name it used to have).
+- `brainglobe-workflows` has been released.
+  - This package provides some exemplar data analysis workflows for users to modify or customise to suit their needs.
+  - It will also provide command-line interfaces for particularly common workflows. Currently it provides `brainmapper`, the successor to the _old_ cellfinder command-line tool.
+- `pip install brainglobe` is now the recommended way to install all BrainGlobe tools.
+  - This will fetch the `brainglobe` meta-package, which includes the latest stable versions of all BrainGlobe tools and napari plugins.
+  - All tools will be accessible in the install environment as if they had been pip-installed directly.
+  - If you are updating to `brainglobe` version 1 having previously installed BrainGlobe tools individually, we [recommend you create](#updating-to-version-1) a clean Python environment and install `brainglobe` into this fresh environment to avoid potential package conflicts.
+  - `brainglobe` package now ships the fixed `brainrender`, as well as `brainrender-napari` which we plan to transition to in the future.

docs/source/documentation/index.md

@@ -1,5 +1,52 @@
 # Documentation
 
+## Installing BrainGlobe
+
+We always recommend that you install BrainGlobe tools into a virtual environment (managed by software such as `conda` or `venv`).
+Your environment should run Python 3.9 or later.
+
+Once you have created and activated your desired environment, you can install all BrainGlobe tools using `pip`:
+
+```bash
+pip install brainglobe
+```
+
+This will fetch all BrainGlobe tools, their Python APIs, and [`napari`](https://napari.org) plugins if they possess one.
+It will also install `napari` into your environment so that you can make use of the plugins.
+
+If you also want to install our command-line tools and/or example workflows, you will also need to install the `brainglobe-workflows` package.
+This package builds on top of the `brainglobe` tools, and provides you with some commonly-used data analysis pipelines to save you from having to write your own scripts for standard workflows.
+You can read about the workflows that are provided [on the documentation page](./brainglobe-workflows/index.md).
+To install `brainglobe-workflows`, run
+
+```bash
+pip install brainglobe-workflows>=1.0.0
+```
+
+in your environment.
+If you didn't previously install `brainglobe` into this environment, `brainglobe-workflows` will do so when you run the command above.
+Otherwise, it will use the version of `brainglobe` that you already have installed.
+
+### Updating
+
+You can update your BrainGlobe tools by running
+
+```bash
+pip install brainglobe --update
+```
+
+in your virtual environment.
+
+### Installing Individual Tools
+
+We recommend installing BrainGlobe in the manner detailed above, however each of the tools in the suite can be individually installed if you so wish.
+This can be done by following the install instructions for the particular tool in question.
+
+Please note that, if you choose to install the tools individually, we cannot guarantee that you will have a consistent and interoperable set of BrainGlobe tools - you may encounter version conflicts or dependency issues.
+If you're not confident in resolving these yourself, we recommend installing BrainGlobe in the manner above; and updating your BrainGlobe tools by updating the overarching `brainglobe` package.
+
+## Individual Tool Documentation
+
 ```{toctree}
 :maxdepth: 1
 setting-up/index
@@ -12,4 +59,4 @@ brainrender/index
 brainglobe-heatmap/index
 cellfinder/index
 morphapi/index
-```
+```