Annotate semaphore.yml

Author: markoa

.semaphore/semaphore.yml

@@ -1,31 +1,67 @@
+# Use the latest stable version of Semaphore 2.0 YML syntax:
 version: v1.0
+
+# Name your pipeline. In case you connect multiple pipelines with promotions,
+# the name will help you differentiate between, for example, a CI build phase
+# and delivery phases.
 name: Semaphore JavaScript Example Pipeline
+
+# An agent defines the environment in which your code runs.
+# It is a combination of one of available machine types and operating
+# system images.
+# See https://docs.semaphoreci.com/article/20-machine-types
+# and https://docs.semaphoreci.com/article/32-ubuntu-1804-image
 agent:
   machine:
     type: e1-standard-2
     os_image: ubuntu1804
 
+# Blocks are the heart of a pipeline and are executed sequentially.
+# Each block has a task that defines one or more jobs. Jobs define the
+# commands to execute.
+# See https://docs.semaphoreci.com/article/62-concepts
 blocks:
   - name: Install dependencies
     task:
+      # Set environment variables that your project requires.
+      # See https://docs.semaphoreci.com/article/66-environment-variables-and-secrets
       env_vars:
         - name: NODE_ENV
           value: test
         - name: CI
           value: 'true'
+
+      # This block runs two jobs in parallel and they both share common
+      # setup steps. We can group them in a prologue.
+      # See https://docs.semaphoreci.com/article/50-pipeline-yaml#prologue
       prologue:
         commands:
+          # Get the latest version of our source code from GitHub:
           - checkout
+
+          # Use the version of Node.js specified in .nvmrc.
+          # Semaphore provides nvm preinstalled.
           - nvm use
           - node --version
           - npm --version
       jobs:
+        # First parallel job:
         - name: client npm install and cache
           commands:
             - cd src/client
+
+            # Restore dependencies from cache. This command will not fail in
+            # case of a cache miss. In case of a cache hit, npm install will
+            # run very fast.
+            # For more info on caching, see https://docs.semaphoreci.com/article/68-caching-dependencies
             - cache restore client-node-modules-$SEMAPHORE_GIT_BRANCH-$(checksum package-lock.json),client-node-modules-$SEMAPHORE_GIT_BRANCH,client-node-modules-master
             - npm install
+
+            # Store the latest version of node modules in cache to reuse in
+            # further blocks:
             - cache store client-node-modules-$SEMAPHORE_GIT_BRANCH-$(checksum package-lock.json) node_modules
+
+        # Second parallel job:
         - name: server npm install and cache
           commands:
             - cd src/server
@@ -50,7 +86,10 @@ blocks:
         - name: Client Lint
           commands:
             - cd src/client
+            # At this point we can assume 100% cache hit rate of node modules:
             - cache restore client-node-modules-$SEMAPHORE_GIT_BRANCH-$(checksum package-lock.json),client-node-modules-$SEMAPHORE_GIT_BRANCH,client-node-modules-master
+
+            # Run task as defined in package.json:
             - npm run lint
         - name: Server Lint
           commands:
@@ -96,10 +135,14 @@ blocks:
           - nvm use
           - node --version
           - npm --version
+          # Start a Postgres database. On Semaphore, databases run in the same
+          # environment as your code.
+          # See https://docs.semaphoreci.com/article/32-ubuntu-1804-image#databases-and-services
           - sem-service start postgres
+          # With unrestricted sudo access, you can install any additional
+          # system package:
           - sudo apt-get install -y libgtk2.0-0
       jobs:
-        # TODO cypress require additional package to be installed on ci server
         - name: Client Tests
           commands:
             - cd src/client