[pitivi/sdk: 3/3] docs: How to update the runtime

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

commit e6c3906d2b24c2d4b4a08d0a6d868f52307a3307
Author: Alexandru Băluț <alexandru balut gmail com>
Date:   Mon Dec 28 00:16:25 2020 +0100

    docs: How to update the runtime
    
    Fixes #2408

 docs/Administrative.md        |  3 ++
 docs/Google_Summer_of_Code.md |  2 +-
 docs/How_to_update_SDK.md     | 64 +++++++++++++++++++++++++++++++++++++++++++
 docs/release.md               |  4 +++
 docs/sitemap.txt              | 16 ++++++-----
 5 files changed, 81 insertions(+), 8 deletions(-)
---
diff --git a/docs/Administrative.md b/docs/Administrative.md
new file mode 100644
index 000000000..78ae8a6d5
--- /dev/null
+++ b/docs/Administrative.md
@@ -0,0 +1,3 @@
+# Maintenance
+
+Tasks a maintainer would be interested performing.
diff --git a/docs/Google_Summer_of_Code.md b/docs/Google_Summer_of_Code.md
index 3c41131a5..d469a8ce7 100644
--- a/docs/Google_Summer_of_Code.md
+++ b/docs/Google_Summer_of_Code.md
@@ -1,4 +1,4 @@
-# Google Summer of Code
+# GSoC
 
 The [Google “Summer of Code” program] is available for students only. If
 we accept your project proposal, in June-July-August you work on your
diff --git a/docs/How_to_update_SDK.md b/docs/How_to_update_SDK.md
new file mode 100644
index 000000000..d6feb8232
--- /dev/null
+++ b/docs/How_to_update_SDK.md
@@ -0,0 +1,64 @@
+---
+short-description: How to update the SDK used by the Pitivi development environment
+...
+
+# How to update the SDK
+
+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 [official
+build](Install_with_flatpak.md).
+
+The Flatpak manifest is based on the `org.gnome.Platform` runtime which needs to
+be updated as soon as possible after new GNOME releases take place.
+
+The complexity in updating the runtime comes from the fact that we use our own
+Docker image for running the tests and this needs to be updated also.
+
+## Update your dev env locally
+
+First, look in `org.pitivi.Pitivi.json` for the current version:
+
+```
+    "runtime-version": "3.38",
+```
+
+Grep the entire repo for this runtime version and replace it with the next
+version.
+
+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!
+
+```
+$ git checkout -b sdk
+$ git push origin sdk
+```
+
+## Build the tests runner image
+
+If you go to Gitlab pitivi page > CI / CD >
+[Schedules](https://gitlab.gnome.org/GNOME/pitivi/-/pipeline_schedules) you can
+see a "Build docker image for the CI" schedule targetting branch "master". This
+rebuilds every 24h the image we use for running the unittests. This image caches
+the build of dependencies described in our Flatpak manifest.
+
+To create an initial image for the new SDK, start with creating a new schedule.
+Set description "build new image", select the branch you just pushed ("sdk"),
+uncheck Active.
+
+Go back to the Schedules page and click the Play button to start a pipeline.
+Notice in the Last Pipeline column a link to the pipeline you just started. When
+it succeeds, you should be able to create a regular MR with your branch to merge
+it.
diff --git a/docs/release.md b/docs/release.md
index bc390f559..4ce22ad3f 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -1,3 +1,7 @@
+---
+short-description: How to make a new release
+...
+
 # How to make a release
 
 Ideally these instructions are in line with the [GNOME releasing
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index 06dbbff88..8da93332b 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -8,25 +8,27 @@ index.md
                Git.md
                Coding_style_guide.md
                Command_line_tools.md
-       The_people.md
-       release.md
+       Testing.md
+               QA_Scenarios.md
        Architecture.md
                GES.md
        Plugins.md
                Advanced_plugin.md
        crossplatform.md
                Mac_OS_X.md
-       Praise.md
-       Project_history.md
-       Current_events.md
        Google_Summer_of_Code.md
                GSoC_Ideas.md
                GSoC_Application.md
                Past_GSoCs.md
                        Google_SoC_2007_-_Simple_Timeline.md
                        Feroze_gsoc.md
-       Testing.md
-               QA_Scenarios.md
+       The_people.md
+       Administrative.md
+               release.md
+               How_to_update_SDK.md
+       Praise.md
+       Project_history.md
+       Current_events.md
        design.md
                design/Why_python.md
                design/Proxy_editing_requirements.md