Version 1 release (#132)

* Add blog, changelog, and install instructions

* Add full changelog in one place with key overviews

* Add full changelog in one place with key overviews

* Update docs/source/blog/version1/version_1_released.md

Co-authored-by: Adam Tyson <[email protected]>

* Apply suggestions from code review

Co-authored-by: Adam Tyson <[email protected]>

* Apply Adam's suggestions

* Add meta-package developer docs

* Add dev link to meta-package docs from main documentation page

* Clarify minor metapackage releases

* Add regenerating diagram text

* Apply suggestions from code review

Co-authored-by: Alessandro Felder <[email protected]>

---------

Co-authored-by: Adam Tyson <[email protected]>
Co-authored-by: Alessandro Felder <[email protected]>

docs/source/blog/version1/version_1_released.md

@@ -0,0 +1,69 @@
+---
+blogpost: true
+date: Jan 8th, 2024
+author: Will Graham
+location: London, England
+category: BrainGlobe-v1
+language: English
+---
+
+# BrainGlobe version 1 is here!
+
+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`
+- `brainglobe-heatmap`
+- `brainglobe-napari-io`
+- `brainglobe-segmentation`
+- `brainreg`
+- `brainrender` and `brainrender-napari` (new with version 1)
+- `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 posts: [Initial move](./cellfinder_migration_live.md) and [renaming](./core_and_napari_merge.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/developers/repositories/brainglobe-meta/index.md

@@ -0,0 +1,101 @@
+# brainglobe-meta
+
+`pip install brainglobe` is doing what you expect - installing a package from PyPI called `brainglobe`.
+This package, colloquially referred to as _the_ "meta"-package, `brainglobe`, and/or `brainglobe-meta`, doesn't actually contain any functionality beyond providing a version and some author information.
+Instead, it's primary purpose is to (explicitly) depend on the other BrainGlobe tools that we want users to be able to install in a single command, through this package.
+You can find the source for this package in the [`brainglobe-meta` repository](https://github.com/brainglobe/brainglobe-meta) on GitHub.
+
+## Installation
+
+The meta-package should always be installable in one line, and preferably should be installed for the first time in a clean environment.
+
+### From `PyPI`, via `pip`
+
+`brainglobe` can be installed from PyPI via
+
+```bash
+pip install brainglobe
+```
+
+or
+
+```bash
+python -m pip install brainglobe
+```
+
+Pass the `-U` or `--update` flag to `pip` to force an update on an existing install.
+
+## Conventions
+
+### Versioning
+
+The rule of thumb for versioning and releasing the meta-package (creating a "new version of `brainglobe`"):
+
+> Any `brainglobe` vX.0.0 release is a set of stable, compatible tools that interoperate with each other consistently.
+> A `brainglobe` vX.Y.0 or vX.Y.Z release should be used when there have been several minor or patch updates to the BrainGlobe tool suite, that we want to encourage the user-base to adopt.
+
+As such, we typically envision major version releases of the meta-package taking place when one or more BrainGlobe tools undergo major updates.
+An example would be the release of `brainglobe` version 1; which saw the various `brainreg` packages merged, the `cellfinder` package was repurposed in order to merge `cellfinder-core` and `cellfinder-napari`, and the `brainmapper` tool replace the (old) cellfinder command-line interface.
+The resulting `brainglobe` version 1.0.0 release prevents users from installing incompatible versions of `brainreg` and `cellfinder`, for example, both by removing the need for users to install these tools manually and by pinning minimum versions for each.
+
+Minor or patch updates to `brainglobe` we envision to be cases where multiple tools have undergone performance improvements, minor patches, or under-the-hood code refactoring that we feel benefits the user experience, but does not require a change in how the user interacts with these tools.
+A typical example of this might be when a function appears in both `brainglobe-tool-A` and `brainglobe-tool-B`, so we decide to refactor it into `brainglobe-utils` which is a common dependency.
+In this case; each of `brainglobe-tool-A`, `brainglobe-tool-B`, and `brainglobe-utils` would get new releases, and furthermore both `brainglobe-tool-A` and `brainglobe-tool-B` would now depend on the new version of `brainglobe-utils`.
+We would then decide to release a minor version of the meta-package, which updates the minimum version of these three packages - from the user perspective, this will come in a single update.
+
+### Dependency Pinning
+
+With the above conventions on versioning in mind, meta-package dependencies are always **pinned from below, and from above by the next major version**.
+As such, all BrainGlobe dependencies in the meta-package `pyproject.toml` will have the form:
+
+```toml
+dependencies = [
+    "brainglobe-tool-1>=X.Y.Z,<(X+1)",
+]
+```
+
+for example,
+
+```toml
+dependencies = [
+    "cellfinder>=1.1.0,<2",
+    "brainrender>=2.1.3,<3",
+]
+```
+
+This ensures that:
+
+- Minor and patch updates to BrainGlobe tools should be picked up automatically by package installer when updating the metapackage. For example, if `cellfinder` bumps from `1.1.3` to `1.2.0`, updating the meta-package will result in `cellfinder` being updated to `1.2.0`.
+- Major or breaking changes to BrainGlobe tools are **not** automatically picked up on update!
+- We can force certain (combinations of) minor/patch updates to tools on users by simply releasing minor/patch updates to `brainglobe`. Changing `cellfinder>=1.1.0,<2` to `cellfinder>=1.1.4,<2` and `brainrender>=2.1.3,<3"` to `brainrender>=2.2.1,<3"`, then creating a new `brainglobe` minor/patch release, allows the user to update both of these packages with an update to `brainglobe`, not having to worry about the individual packages themselves.
+
+## Dependency Tree
+
+BrainGlobe comprises a number of tools, spread across a number of repositories.
+These tools are all interlinked and interdependent, but the meta-package allows us to abstract this complexity away from the user.
+
+To ensure we retain explicit control over what `brainglobe` provides to users, it is important that the meta-package explicitly depends on all BrainGlobe tools that it wants to provide, including "redundant dependencies".
+For example, if the meta-package is providing `brainglobe-tool-A`, which itself depends on `brainglobe-tool-B`, then the dependency list of the meta-package should include **both** `brainglobe-tool-A` and `brainglobe-tool-B`.
+Both packages should also have minimum versions pinned as per the [dependency pinning guidelines](#dependency-pinning) above.
+
+The dependency tree of BrainGlobe tools provided by the meta-package is provided below, and should be updated periodically as new tools are added, or new versions of `brainglobe` are released.
+Whilst it is not necessary for developers to remember the dependency structure, it is a useful reference guide for discerning how updates to one BrainGlobe tool might have knock-on effects on others.
+The dependency tree reads top-to-bottom; that is, arrows are drawn **out** of dependencies **into** the tools that depend on them.
+The tree does not include non-BrainGlobe dependencies.
+Coloured arrows are only present to allow for line-tracing when arrows cross.
+
+![Dependency tree for tools provided by the meta-package.](./brainglobe-dependencies.svg)
+
+### Regenerating the Dependency Tree
+
+The image file containing the dependency tree is saved under `<repo_root>/docs/source/community/developers/repositories/brainglobe-meta/brainglobe-dependencies.svg`.
+It can be edited with any software that can open and manipulate `.svg` files, however the recommended tool is [`drawio`](https://app.diagrams.net/) which provides a GUI for editing `.svg`s.
+Simply upload the current version of the file to the website, edit the flowchart as you see fit, then hit `File > Export As... > SVG`, which will open a further dialogue box with export options.
+In this box, be sure to select "`Text Settings: Convert Labels to SVG`" to ensure that the exported flowchart's text is encoded correctly.
+You can then export the file and save the new version to the repository.
+
+As a general rule of thumb when editing the dependency chart, packages/tools should be organised into levels from the top down, with arrows pointing _out of dependencies_ **into** _the dependent packages_.
+
+Packages on the top level depend on no other BrainGlobe tools.
+Packages on the level below depend on at least one package from the level above, and any number of packages from the level(s) further up than that.
+This illustrates both how BrainGlobe tools build on each other, as well as which tools may be affected by new releases of others.

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

@@ -1,5 +1,25 @@
 # 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.
+
+If you want to know more about the under-the-hood workings of the `brainglobe` "meta"-package, you can head to the [developer documentation](/docs/source/community/developers/repositories/brainglobe-meta/index.md).
+
+## 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.
+
+### Can I install from `conda-forge`?
+
+We are working on providing a `conda-forge` install for BrainGlobe version 1, as an alternative to the `pip install brainglobe` command that we currently recommend.
+However for the time being, there is no one-line installation possible using `conda`.
+
+There are no problems with `pip install brainglobe`-ing into a `conda` environment, we just need some time to setup all of the individual BrainGlobe tools on `conda-forge` before we can provide an all-in-one install through `conda`!
+
 ## Changes at-a-glance
 
 Below is a high-level overview of the changes to the brainglobe suite of tools that we offer.
@@ -13,8 +33,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 +44,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` which only performs cell detection. The command-line tool will use the name `brainmapper`.
+  - 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.