Add some doc to the github actions / CI scripts (#8034)

* Add some doc to the githuib actions / CI scripts

Type: task

* alalytics-events is more name matching

.github/workflows/develop.yml → .github/workflows/end-to-end-tests.yaml

@@ -1,4 +1,4 @@
-name: Develop
+name: End-to-end Tests
 on:
     # These tests won't work for non-develop branches at the moment as they
     # won't pull in the right versions of other repos, so they're only enabled
@@ -11,6 +11,7 @@ jobs:
     end-to-end:
         runs-on: ubuntu-latest
         env:
+          # This must be set for fetchdep.sh to get the right branch
           PR_NUMBER: ${{github.event.number}}
         container: vectorim/element-web-ci-e2etests-env:latest
         steps:

.github/workflows/layered-build.yaml

@@ -1,10 +1,13 @@
+# Produce a 'layered build' (a build of element-web with this version of
+# react-sdk) and output it as an artifact
 name: Layered Preview Build
 on:
     pull_request:
 jobs:
     build:
         runs-on: ubuntu-latest
         env:
+          # This must be set for fetchdep.sh to get the right branch
           PR_NUMBER: ${{github.event.number}}
         steps:
             - uses: actions/checkout@v2

.github/workflows/netlify.yaml

@@ -1,3 +1,5 @@
+# Triggers after the layered build has finished, taking the artifact
+# and uploading it to netlify
 name: Upload Preview Build to Netlify
 on:
     workflow_run:

.github/workflows/test_coverage.yml

@@ -7,6 +7,7 @@ jobs:
   test-coverage:
     runs-on: ubuntu-latest
     env:
+      # This must be set for fetchdep.sh to get the right branch
       PR_NUMBER: ${{github.event.number}}
     steps:
       - name: Checkout code

.github/workflows/typecheck.yaml

@@ -6,6 +6,7 @@ jobs:
     build:
         runs-on: ubuntu-latest
         env:
+          # This must be set for fetchdep.sh to get the right branch
           PR_NUMBER: ${{github.event.number}}
         steps:
             - uses: actions/checkout@v2

scripts/ci/Dockerfile

@@ -1,3 +1,5 @@
+# Docker file for end-to-end tests
+
 # Update on docker hub with the following commands in the directory of this file:
 # If you're on linux amd64
 #   docker build -t vectorim/element-web-ci-e2etests-env:latest .

scripts/ci/install-deps.sh

@@ -1,5 +1,12 @@
 #!/bin/bash
 
+# This installs other Matrix dependencies that are often
+# developed in parallel with react-sdk, using fetchdep.sh
+# for branch matching.
+# This will set up a working react-sdk environment, so is
+# used for running react-sdk standalone tests. To set up a
+# build of element-web, use layered.sh
+
 set -ex
 
 scripts/fetchdep.sh matrix-org matrix-js-sdk

scripts/ci/layered.sh

@@ -1,7 +1,9 @@
 #!/bin/bash
 
 # Creates a layered environment with the full repo for the app and SDKs cloned
-# and linked.
+# and linked. This gives an element-web dev environment ready to build with
+# the current react-sdk branch and any matching branches of react-sdk's dependencies
+# so that changes can be tested in element-web.
 
 # Note that this style is different from the recommended developer setup: this
 # file nests js-sdk and element-web inside react-sdk, while the local
@@ -16,7 +18,8 @@ yarn link
 yarn install --pure-lockfile
 popd
 
-# Set up the js-sdk first
+# Also set up matrix-analytics-events so we get the latest from
+# the main branch or a branch with matching name
 scripts/fetchdep.sh matrix-org matrix-analytics-events main
 pushd matrix-analytics-events
 yarn link