Update baseline creation instruction (#2435)

baselines/README.md

@@ -49,7 +49,7 @@ Do you have a new federated learning paper and want to add a new baseline to Flo
 The steps to follow are:
 
 1. Fork the Flower repo and clone it into your machine.
-2. Navigate to the `baselines/` directory and from there run:
+2. Navigate to the `baselines/` directory, choose a single-word (and **lowercase**) name for your baseline, and from there run:
 
     ```bash
     # This will create a new directory with the same structure as `baseline_template`.

baselines/doc/source/tutorial-contribute-baselines.rst → baselines/doc/source/how-to-contribute-baselines.rst

@@ -7,23 +7,31 @@ The goal of Flower Baselines is to reproduce experiments from popular papers to
 
 Before you start to work on a new baseline or experiment, please check the `Flower Issues <https://github.com/adap/flower/issues>`_ or `Flower Pull Requests <https://github.com/adap/flower/pulls>`_ to see if someone else is already working on it. Please open a new issue if you are planning to work on a new baseline or experiment with a short description of the corresponding paper and the experiment you want to contribute.
 
-TL;DR: Add a new Flower Baseline
---------------------------------
-.. warning::
-    We are in the process of changing how Flower Baselines are structured and updating the instructions for new contributors. Bear with us until we have finalised this transition. For now, follow the steps described below and reach out to us if something is not clear. We look forward to welcoming your baseline into Flower!!
+Requirements
+------------
+
+Contributing a new baseline is really easy. You only have to make sure that your federated learning experiments are running with Flower and replicate the results of a paper. Flower baselines need to make use of:
+
+* `Poetry <https://python-poetry.org/docs/>`_ to manage the Python environment.
+* `Hydra <https://hydra.cc/>`_ to manage the configuration files for your experiments.
+
+You can find more information about how to setup Poetry in your machine in the ``EXTENDED_README.md`` that is generated when you prepare your baseline. 
+
+Add a new Flower Baseline
+-------------------------
 .. note::
-    For a detailed set of steps to follow, check the `Baselines README on GitHub <https://github.com/adap/flower/tree/main/baselines>`_.
+    The instructions below are a more verbose version of what's present in the `Baselines README on GitHub <https://github.com/adap/flower/tree/main/baselines>`_.
 
 Let's say you want to contribute the code of your most recent Federated Learning publication, *FedAwesome*. There are only three steps necessary to create a new *FedAwesome* Flower Baseline:
 
 #. **Get the Flower source code on your machine**
     #. Fork the Flower codebase: go to the `Flower GitHub repo <https://github.com/adap/flower>`_ and fork the code (click the *Fork* button in the top-right corner and follow the instructions)
     #. Clone the (forked) Flower source code: :code:`git clone [email protected]:[your_github_username]/flower.git`
     #. Open the code in your favorite editor.
-#. **Create a directory for your baseline and add the FedAwesome code**
+#. **Use the provided script to create your baseline directory**
     #. Navigate to the baselines directory and run :code:`./dev/create-baseline.sh fedawesome`
     #. A new directory in :code:`baselines/fedawesome` is created.
-    #. Follow the instructions in :code:`EXTENDED_README.md` and :code:`README.md` in :code:`baselines/fedawesome/`. 
+    #. Follow the instructions in :code:`EXTENDED_README.md` and :code:`README.md` in your baseline directory. 
 #. **Open a pull request**
     #. Stage your changes: :code:`git add .`
     #. Commit & push: :code:`git commit -m "Create new FedAwesome baseline" ; git push`
@@ -36,18 +44,20 @@ Further reading:
 * `GitHub docs: Creating a pull request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_
 * `GitHub docs: Creating a pull request from a fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_
 
-Requirements
-------------
-
-Contributing a new baseline is really easy. You only have to make sure that your federated learning experiments are running with Flower and replicate the results of a paper. 
-
-The only requirement you need in your system in order to create a baseline is to have `Poetry <https://python-poetry.org/docs/>`_ installed. This is our package manager tool of choice. 
 
-We are adopting `Hydra <https://hydra.cc/>`_ as the default mechanism to manage everything related to config files and the parameterisation of the Flower baseline.
 
 Usability
 ---------
 
-Flower is known and loved for its usability. Therefore, make sure that your baseline or experiment can be executed with a single command such as :code:`conda run -m <your-baseline>.main` or :code:`python main.py` (when sourced into your environment). We provide you with a `template-baseline <https://github.com/adap/flower/tree/main/baselines/baseline_template>`_ to use as guidance when contributing your baseline. Having all baselines follow a homogenous structure helps users to tryout many baselines without the overheads of having to understand each individual codebase. Similarly, by using Hydra throughout, users will immediately know how to parameterise your experiments directly from the command line.
+Flower is known and loved for its usability. Therefore, make sure that your baseline or experiment can be executed with a single command such as:
+
+.. code-block:: bash
+
+  poetry run python -m <your-baseline>.main
+  
+  # or, once sourced into your environment
+  python -m <your-baseline>.main
+
+We provide you with a `template-baseline <https://github.com/adap/flower/tree/main/baselines/baseline_template>`_ to use as guidance when contributing your baseline. Having all baselines follow a homogenous structure helps users to tryout many baselines without the overheads of having to understand each individual codebase. Similarly, by using Hydra throughout, users will immediately know how to parameterise your experiments directly from the command line.
 
 We look forward to your contribution!

baselines/doc/source/tutorial-use-baselines.rst → baselines/doc/source/how-to-use-baselines.rst

@@ -45,10 +45,3 @@ To install Poetry on a different OS, to customise your installation, or to furth
     poetry install
 
 3. Run the baseline as indicated in the :code:`[Running the Experiments]` section in the :code:`README.md` 
-
-
-Available Baselines
--------------------
-
-.. note::
-  To be updated soon once the existing baselines are adjusted to the new format.

baselines/doc/source/index.rst

@@ -19,29 +19,32 @@ The Flower Community is growing quickly - we're a friendly group of researchers,
 Flower Baselines
 ----------------
 
-Flower Baselines are a collection of organised scripts used to reproduce results from well-known publications or benchmarks. You can check which baselines already exist and/or contribute your own baseline.
+Flower Baselines are a collection of organised directories used to reproduce results from well-known publications or benchmarks. You can check which baselines already exist and/or contribute your own baseline.
 
 .. BASELINES_TABLE_ANCHOR
 
+
 Tutorials
 ~~~~~~~~~
 
 A learning-oriented series of tutorials, the best place to start.
 
-.. toctree::
-  :maxdepth: 1
-  :caption: Tutorials
-
-  tutorial-use-baselines
-  tutorial-contribute-baselines
+.. note::
+  Coming soon
+
 
 How-to guides
 ~~~~~~~~~~~~~
 
 Problem-oriented how-to guides show step-by-step how to achieve a specific goal.
 
-.. note::
-  Coming soon
+.. toctree::
+  :maxdepth: 1
+  :caption: How-to Guides
+
+  how-to-use-baselines
+  how-to-contribute-baselines
+
 
 Explanations
 ~~~~~~~~~~~~

doc/source/ref-changelog.md

@@ -28,7 +28,7 @@
 
 - **Update Flower Examples** ([#2384](https://github.com/adap/flower/pull/2384)), ([#2425](https://github.com/adap/flower/pull/2425))
 
-- **General updates to baselines** ([#2301](https://github.com/adap/flower/pull/2301), [#2305](https://github.com/adap/flower/pull/2305), [#2307](https://github.com/adap/flower/pull/2307), [#2327](https://github.com/adap/flower/pull/2327))
+- **General updates to baselines** ([#2301](https://github.com/adap/flower/pull/2301), [#2305](https://github.com/adap/flower/pull/2305), [#2307](https://github.com/adap/flower/pull/2307), [#2327](https://github.com/adap/flower/pull/2327), [#2435](https://github.com/adap/flower/pull/2435))
 
 - **General updates to the simulation engine** ([#2331](https://github.com/adap/flower/pull/2331), [#2447](https://github.com/adap/flower/pull/2447), [#2448](https://github.com/adap/flower/pull/2448))