add developer-specific instructions to docs/instructions.rst and include them in the ToC

docs/index.rst

@@ -48,10 +48,16 @@ For more information, go to `the Stackspin website`_.
    troubleshooting
    security
 
+.. toctree::
+   :maxdepth: 2
+   :caption: For Developers
+
+   design
+   instructions
+
 .. toctree::
    :maxdepth: 2
    :caption: Reference
 
    reference
    comparable_projects
-   design

docs/instructions.rst

+Instructions
+============
+
+This document contains instructions for a few tasks that you might have to do as
+a Stackspin developer
+
+Building a new version of Zulip
+-------------------------------
+
+As long as Zulip version 5 is not released yet, you need to build it from the
+source code's ``main`` branch every once in a while. In order to do so, you need
+the following:
+
+1. The commit ref of the version of the `Zulip repository
+   <https://github.com/zulip/zulip>`__ you want to build, e.g.
+   ``5e90b32f40ad45d59e00a4e5c08cc6f180e04d30``
+2. An abbreviated version of the commit ref. We take the first ten characters of
+   the whole ref, ``5e90b32f40`` in our example.
+3. A local copy of our fork of `the docker-zulip repository
+   <https://github.com/greenhost/docker-zulip>`__ (at least until `our pull
+   request is merged <https://github.com/zulip/docker-zulip/pull/325>`__
+
+   This is necessary because we have added the ``SOCIAL_AUTH_OIDC_ENABLED_IDPS``
+   variable to the ``entrypoint.sh`` docker entrypoint script. Without our
+   changes, setting OIDC settings through environment variables is impossible.
+
+Once you have these two things, you can run the following build command to build
+the container:
+
+.. code::
+
+   docker build \
+     --build-arg "ZULIP_GIT_REF=5e90b32f40ad45d59e00a4e5c08cc6f180e04d30" \
+     -t open.greenhost.net:4567/stackspin/stackspin/zulip:5e90b32f40 \
+     .
+
+The build argument ZULIP_GIT_REF tells the Dockerfile to use that ref when
+checking out and building Zulip. The tag is necessary so you can push the new
+Zulip container to our registry after building with the following command:
+
+.. code::
+
+   docker push open.greenhost.net:4567/stackspin/stackspin/zulip:5e90b32f40
+
+Once the push is completed, you can edit the tag in
+``flux2/apps/zulip/zulip-values-configmap.yaml`` and create a PR to update Zulip
+in Stackspin.
+
+Once our PR has been merged **and** Zulip version 5 has been released, this
+guide is obsolete and Stackspin can use docker images as provided by Zulip on
+Docker hub.