docs: Update pieces of documentation after the release of mamba 2 (#3610

) Signed-off-by: Julien Jerphanion <[email protected]> Co-authored-by: Lucas Colley <[email protected]> Co-authored-by: Johan Mabille <[email protected]>
mamba-org · Nov 18, 2024 · d42b8c2 · d42b8c2
1 parent ad9b2d6
commit d42b8c2
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -12,7 +12,6 @@
   <tr background="#FFF">
     <td align="center">Package Manager <a href="https://github.com/mamba-org/mamba">mamba</a></td>
     <td align="center">Package Server <a href="https://github.com/mamba-org/quetz">quetz</a></td>
-    <td align="center">Package Builder <a href="https://github.com/mamba-org/boa">boa</a></td>
   </tr>
 </tbody>
 </table>
@@ -31,8 +30,29 @@
 
 At the same time, `mamba` utilizes the same command line parser, package installation and deinstallation code and transaction verification routines as `conda` to stay as compatible as possible.
 
-Mamba is part of a bigger ecosystem to make scientific packaging more sustainable. You can read our [announcement blog post](https://medium.com/@QuantStack/open-software-packaging-for-science-61cecee7fc23).
-The ecosystem also consists of `quetz`, an open source `conda` package server and `boa`, a fast `conda` package builder.
+`mamba` is part of the [conda-forge](https://conda-forge.org/) ecosystem, which also consists of `quetz`, an open source `conda` package server.
+
+You can read our [announcement blog post](https://medium.com/@QuantStack/open-software-packaging-for-science-61cecee7fc23).
+
+## micromamba
+
+`micromamba` is the statically linked version of `mamba`.
+
+It can be installed as a standalone executable without any dependencies, making it a perfect fit for CI/CD pipelines and containerized environments.
+
+See the [documentation on `micromamba`](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) for details.
+
+## `mamba` v.s. `micromamba`
+
+`mamba` has to be preferred when:
+  - `libmambapy` or `libmamba` is used by other software in the same environment.
+  - Scenarios where regular updates to libraries are required (especially for security).
+  - Environments are focused on reducing disk space usage for dependencies.
+
+`micromamba` has to be preferred when:
+  - Relying a single self-contained executable is required.
+  - A miniforge distribution is not present.
+  - Usage requires minimal runtime.
 
 ## Installation
 
@@ -45,33 +65,35 @@ Please refer to the [mamba](https://mamba.readthedocs.io/en/latest/installation/
 ### `repoquery`
 
 To efficiently query repositories and query package dependencies you can use `mamba repoquery` or `micromamba repoquery`.
+
 See the [repoquery documentation](https://mamba.readthedocs.io/en/latest/user_guide/mamba.html#repoquery) for details.
 
 ### Installing lock files
 
-`micromamba` can be used to install lock files generated by [conda-lock](https://conda.github.io/conda-lock/) without having to install `conda-lock`. Simply invoke e.g. `micromamba create -n my-env -f conda-lock.yml` with an environment lockfile named `*-lock.yml` or `*-lock.yaml`.
+`micromamba` can be used to install lock files generated by [conda-lock](https://conda.github.io/conda-lock/) without having to install `conda-lock`.
+
+Simply invoke e.g. `micromamba create -n my-env -f conda-lock.yml` with an environment lockfile named `*-lock.yml` or `*-lock.yaml`.
 
 ### setup-micromamba (setup-miniconda replacement)
 
 [setup-micromamba](https://github.com/marketplace/actions/setup-micromamba) is a replacement for [setup-miniconda](https://github.com/marketplace/actions/setup-miniconda) that uses `micromamba`.
+
 It can significantly reduce your CI setup time by:
 
 - Using `micromamba`, which takes around 1 s to install.
 - Caching package downloads.
 - Caching entire `conda` environments.
 
-## micromamba
-
-`micromamba` is a small, pure-C++ reimplementation of `mamba`/`conda`. It strives to be a full replacement for `mamba` and `conda`. As such, it doesn't use any `conda` code (in fact it doesn't require Python at all).
-
-See the [documentation on `micromamba`](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) for details.
-
 ## Development installation
 
 Please refer to the instructions given by the [official documentation](https://mamba.readthedocs.io/en/latest/developer_zone/dev_environment.html).
 
 ## Support us
 
+Only `mamba` and `micromamba` 2.0 and later are supported and are actively developed.
+
+The `1.x` branch is only maintained for addressing security issues such as CVEs.
+
 For questions, you can also join us on the [QuantStack Chat](https://gitter.im/QuantStack/Lobby) or on the [Conda channel](https://gitter.im/conda/conda) (note that this project is not officially affiliated with `conda` or Anaconda Inc.).
 
 ## License

diff --git a/docs/source/developer_zone/changes-2.0.rst b/docs/source/developer_zone/changes-2.0.rst
@@ -14,10 +14,12 @@ Command Line Executables
 ------------------------
 Mamba (executable)
 ******************
-``mamba``, previously a Python executable mixing ``libmambapy``, ``conda``, and code to bridge both
-project is being replace by a fully C++ executable based on ``libmamba`` solely.
 
-It now presents the same user interface and experience as ``micromamba``.
+``mamba``, previously a Python executable mixing ``libmambapy``, ``conda``, and some specific code logic
+has been entirely replaced by the dynamically linked version of ``micromamba``,
+a statically-linked ELF based on ``libmamba``.
+
+Hence ``mamba``` now has the exact same user interface and experience as ``micromamba``.
 
 .. warning::
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -5,11 +5,12 @@ Mamba is a fast, robust, and cross-platform package manager.
 
 It runs on Windows, OS X and Linux (ARM64 and PPC64LE included) and is fully compatible with ``conda`` packages and supports most of conda's commands.
 
-The ``mamba-org`` organization hosts multiple Mamba flavors:
+Mamba is a framework with several components:
 
-- ``mamba``: a Python-based CLI conceived as a *drop-in* replacement for ``conda``, offering higher speed and more reliable environment solutions
-- ``micromamba``: a pure C++-based CLI, self-contained in a single-file executable
-- ``libmamba``: a C++ library exposing low-level and high-level APIs on top of which both ``mamba`` and ``micromamba`` are built
+- ``libmamba``: a C++ library of the domain, exposing low-level and high-level APIs
+- ``mamba``: a ELF as a *drop-in* replacement for ``conda``, built on top of ``libmamba``
+- ``micromamba``: the statically linked version of ``mamba``
+- ``libmambapy``: python bindings of ``libmamba``
 
 .. note::
    In this documentation, ``Mamba`` will refer to all flavors while flavor-specific details will mention ``mamba``, ``micromamba`` or ``libmamba``.