From 8b44a63b475c325a91b216a1ff894755aa905a05 Mon Sep 17 00:00:00 2001
From: Javier <jafermarq@users.noreply.github.com>
Date: Thu, 7 Dec 2023 12:40:14 +0000
Subject: [PATCH] Update contributor dev env setup guide (#2646)

---
 ...-tutorial-get-started-as-a-contributor.rst | 47 ++++++++++++++-----
 1 file changed, 35 insertions(+), 12 deletions(-)

diff --git a/doc/source/contributor-tutorial-get-started-as-a-contributor.rst b/doc/source/contributor-tutorial-get-started-as-a-contributor.rst
index e035d1b9867d..72c6df5fdbc7 100644
--- a/doc/source/contributor-tutorial-get-started-as-a-contributor.rst
+++ b/doc/source/contributor-tutorial-get-started-as-a-contributor.rst
@@ -4,7 +4,7 @@ Get started as a contributor
 Prerequisites
 -------------
 
-- `Python 3.7 <https://docs.python.org/3.7/>`_ or above
+- `Python 3.8 <https://docs.python.org/3.8/>`_ or above
 - `Poetry 1.3 <https://python-poetry.org/>`_ or above
 - (Optional) `pyenv <https://github.com/pyenv/pyenv>`_
 - (Optional) `pyenv-virtualenv <https://github.com/pyenv/pyenv-virtualenv>`_
@@ -17,26 +17,49 @@ supports `PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_.
 Developer Machine Setup
 -----------------------
 
-First, clone the `Flower repository <https://github.com/adap/flower>`_ from
+Preliminarities
+~~~~~~~~~~~~~~~
+Some system-wide dependencies are needed.
+
+For macOS
+^^^^^^^^^
+
+* Install `homebrew <https://brew.sh/>`_. Don't forget the post-installation actions to add `brew` to your PATH.
+* Install `xz` (to install different Python versions) and `pandoc` to build the
+  docs::
+    
+  $ brew install xz pandoc
+
+For Ubuntu
+^^^^^^^^^^
+Ensure you system (Ubuntu 22.04+) is up-to-date, and you have all necessary
+packages::
+
+  $ apt update
+  $ apt install build-essential zlib1g-dev libssl-dev libsqlite3-dev \
+                libreadline-dev libbz2-dev libffi-dev liblzma-dev pandoc
+
+
+Create Flower Dev Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Clone the `Flower repository <https://github.com/adap/flower>`_ from
 GitHub::
 
   $ git clone git@github.com:adap/flower.git
   $ cd flower
 
-Second, create a virtual environment (and activate it). If you chose to use
-:code:`pyenv` (with the :code:`pyenv-virtualenv` plugin) and already have it installed
-, you can use the following convenience script (by default it will use :code:`Python 3.8.17`,
-but you can change it by providing a specific :code:`<version>`)::
+2. Let's create the Python environment for all-things Flower. If you wish to use :code:`pyenv`, we provide two convenience scripts that you can use. If you prefer using something else than :code:`pyenv`, create a new environment, activate and skip to the last point where all packages are installed.
 
-  $ ./dev/venv-create.sh <version>
+* If you don't have :code:`pyenv` installed, the following script that will install it, set it up, and create the virtual environment (with :code:`Python 3.8.17` by default)::
 
-If you don't have :code:`pyenv` installed,
-you can use the following script that will install pyenv,
-set it up and create the virtual environment (with :code:`Python 3.8.17` by default)::
+  $ ./dev/setup-defaults.sh <version> # once completed, run the bootstrap script
+  
+* If you already have :code:`pyenv` installed (along with the :code:`pyenv-virtualenv` plugin), you can use the following convenience script (with :code:`Python 3.8.17` by default)::
 
-  $ ./dev/setup-defaults.sh <version>
+  $ ./dev/venv-create.sh <version> # once completed, run the `bootstrap.sh` script
 
-Third, install the Flower package in development mode (think
+3. Install the Flower package in development mode (think
 :code:`pip install -e`) along with all necessary dependencies::
 
   (flower-<version>) $ ./dev/bootstrap.sh