[pitivi/soundtouch] docs: Detail how to update the sandbox

[Alexandru Băluț <alexbalut src gnome org>]

commit 6121e96b96781c4da20cc85dd2a1a6a430c29a58
Author: Alexandru Băluț <alexandru balut gmail com>
Date:   Wed Oct 27 01:28:34 2021 +0200

    docs: Detail how to update the sandbox

 docs/How_to_update_SDK.md            | 64 -------------------------
 docs/How_to_update_sandbox.md        | 92 ++++++++++++++++++++++++++++++++++++
 docs/Updating_Python_dependencies.md |  6 +--
 docs/sitemap.txt                     |  2 +-
 4 files changed, 96 insertions(+), 68 deletions(-)
---
diff --git a/docs/How_to_update_sandbox.md b/docs/How_to_update_sandbox.md
new file mode 100644
index 000000000..8b65aaf4a
--- /dev/null
+++ b/docs/How_to_update_sandbox.md
@@ -0,0 +1,92 @@
+---
+short-description: How to update the sandbox used by the Pitivi development environment
+...
+
+# Updating the sandbox
+
+We use the same [Flatpak
+manifest](https://gitlab.gnome.org/GNOME/pitivi/blob/master/build/flatpak/org.pitivi.Pitivi.json)
+for both the [development environment](HACKING.md) sandbox and for the [nightly
+build snapshot](Install_with_flatpak.md).
+
+To have the CI run the tests as fast as possible, we use a Docker image with
+all the sandbox dependencies cached. This image needs to be updated whenever
+we want to update the manifest, otherwise the CI fails since it can't download
+the latest dependencies.
+
+## Update the flatpak runtime
+
+To update the flatpak runtime version, look in `org.pitivi.Pitivi.json` for the
+current version:
+
+```
+    "runtime-version": "40",
+```
+
+Check out what is the latest flatpak runtime version. For example:
+
+```
+$ flatpak remote-ls flathub --system | grep org.gnome.Platform
+GNOME Application Platform version 3.38        org.gnome.Platform              3.38
+GNOME Application Platform version 40  org.gnome.Platform              40
+GNOME Application Platform version 41  org.gnome.Platform              41
+```
+
+Check out in the git history how we updated the runtime version in the past and
+replace it with the latest release.
+
+
+## Update the sandbox dependencies
+
+Some of them can be updated automatically with
+[flatpak-external-data-checker](https://github.com/flathub/flatpak-external-data-checker):
+
+```
+$ flatpak run --filesystem=$HOME/dev/pitivi/pitivi org.flathub.flatpak-external-data-checker 
build/flatpak/org.pitivi.Pitivi.json --update
+```
+
+Others have to be checked and updated manually.
+
+Most of the [Python dependencies](Updating_Python_dependencies.md) can be
+updated with `flatpak-pip-generator`.
+
+
+## Rebuild your local dev env
+
+```
+$ . bin/pitivi-env
+(ptv-flatpak) $ ptvenv --update
+```
+
+Run the tests:
+
+```
+(ptv-flatpak) $ ptvtests
+```
+
+If all goes well, push the branch to origin to be able to initiate the
+generation of the CI image.
+
+```
+$ git checkout -b sdk
+$ git push origin sdk
+```
+
+## Build the CI image
+
+The "Build docker image for the CI" [GitLab
+Schedule](https://gitlab.gnome.org/GNOME/pitivi/-/pipeline_schedules) rebuilds
+every 24h the image we use for running the unittests. This image caches
+the build of dependencies described in our Flatpak manifest.
+
+Since it's using the "master" branch, you have to create a new schedule and
+select the branch you just pushed ("sdk"). Leave Active unchecked.
+
+Go back to the Schedules page and click the Play button of the schedule you just
+created to start a pipeline. Notice in the Last Pipeline column a link to the
+pipeline you just started.
+
+After the pipeline succeeds, create a regular MR with your manifest changes and
+notice the CI is green. If you fail to merge the MR, the "Build docker image for
+the CI" will kick in later and recreate the image according to the manifest on
+branch "master".
diff --git a/docs/Updating_Python_dependencies.md b/docs/Updating_Python_dependencies.md
index c8a0516b5..9989182bc 100644
--- a/docs/Updating_Python_dependencies.md
+++ b/docs/Updating_Python_dependencies.md
@@ -4,8 +4,8 @@ short-description: How to update the Python dependencies
 
 # Python dependencies
 
-Pitivi has a single Python runtime dependency `matplotlib` but in the
-development sandbox we install quite a few Python tools.
+Pitivi has only two Python runtime dependencies: `librosa` and `matplotlib`, but
+in the development sandbox we install quite a few Python tools.
 
 Each Python package has its own `python3-*.json` file in
 [build/flatpak](https://gitlab.gnome.org/GNOME/pitivi/-/tree/master/build/flatpak),
@@ -25,7 +25,7 @@ build dependencies which have to be installed beforehand. Jan 2021 it's much
 easier to install the compiled packages instead of the source packages. When
 upstream makes it easier to use source packages we should switch.
 
-## Updating actual dependencies
+## Updating runtime dependencies
 
 ```
 $ cd build/flatpak
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index 1be0dc6cb..96fe348a1 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -27,7 +27,7 @@ index.md
        The_people.md
        Administrative.md
                release.md
-               How_to_update_SDK.md
+               How_to_update_sandbox.md
                Updating_Python_dependencies.md
                Precommit_hooks.md
        Praise.md