Update comments

.github/workflows/docker.yml

@@ -1,85 +1,86 @@
 name: build catadog
 
 on:
-  # trigger catadog every time a push occurs on any branch
   push: 
     branches:
       - "**"
 
 env:
-  # push images to the github container registry
   REGISTRY: ghrc.io
-  # store images in the datadog/catadog repository
   REPO: datadog/catadog
 
 jobs:
   build:
     strategy:
-      # in matrix strategy where you're running multiple jobs with different variable combinations, setting fail-fast to false lets jobs continue running despite other failed jobs
       fail-fast: false
-      # not sure if we need a matrix strategy to test multiple different versions of ruby... catadog's base image is ruby 3.4 so maybe we should only have ruby 3.4?
+      # Test only ruby 3.4
       matrix:
         include:
           - engine: ruby
             version: "3.4"
     runs-on: ubuntu-latest
     name: build (${{ matrix.engine }} ${{ matrix.version }})
     steps:
-      - name: set variables
+      - name: Set variables
         id: vars
         run: |
           echo "SRC=." >> $GITHUB_OUTPUT
           echo "IMAGE=${{ env.REGISTRY }}/${{ env.REPO }}/engines/${{ matrix.engine }}" >> $GITHUB_OUTPUT
           echo "TAG=${{ matrix.version }}" >> $GITHUB_OUTPUT
           echo "DOCKERFILE=./Dockerfile" >> $GITHUB_OUTPUT
-      # check out repository code
-      - name: checkout
+      - name: Checkout
         uses: actions/checkout@v4
-      # docker container engine enables advanced buildx features, possibly to allow different platforms (x86_64 and aarch64-linux)
-      - name: set up docker container engine
+
+      # Use docker-container engine to enable advanced buildx features
+      - name: Set up docker container engine
         run: |
           docker buildx create --name=container --driver=docker-container --use --bootstrap
-      # build x86_64 image
-      - name: build single-arch image (x86_64)
+
+      # Build image for x86-64
+      # 
+      # Tag image separately to avoid interference with caching and so that testing step can reference the image
+      - name: Build single-arch image (x86-64)
         run: |
           docker buildx build ${{ steps.vars.outputs.SRC }} --builder=container --cache-from=type=registry,ref=${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} --output=type=image,push=false --platform linux/x86_64 -f ${{ steps.vars.outputs.DOCKERFILE }}
-      # tag image so that it can be referenced in testing step. tag separately from build to avoid interference w caching
-      - name: tag single-arch image (x86_64)
+      - name: Tag single-arch image (x86-64)
         run: |
           docker buildx build ${{ steps.vars.outputs.SRC }} --builder=container --cache-from=type=registry,ref=${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} --load --platform linux/x86_64 -f ${{ steps.vars.outputs.DOCKERFILE }} --tag ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }}
-      # test image 
-      - name: test single-arch image (x86_64)
+      - name: Test single-arch image (x86-64)
         run: |
           docker run --platform linux/x86_64 --rm ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} /bin/sh -c 'true'
           docker run --platform linux/x86_64 --rm ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} ruby -e 'puts RUBY_DESCRIPTION'
           docker run --platform linux/x86_64 --rm ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} gem --version
           docker run --platform linux/x86_64 --rm ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} bundle --version
           docker run --platform linux/x86_64 --rm -v "${PWD}":"${PWD}" -w "${PWD}" ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} /bin/sh -c 'bundle install && bundle exec rake test'
 
-      # now build image for aarch64-linux, emulated under qemu
-      - name: enable aarch64 emulation (x86_64)
+      # Build image for aarch64-linux, emulated under qemu
+      # 
+      # Tag image separately to avoid interference with caching and so that testing step can reference the image
+      - name: Enable aarch64 emulation (x86-64)
         run: |
           docker run --privileged --rm tonistiigi/binfmt --install arm64
-      - name: build single-arch image (aarch64-linux)
+      - name: Build single-arch image (aarch64-linux)
         run: |
           docker buildx build ${{ steps.vars.outputs.SRC }} --builder=container --cache-from=type=registry,ref=${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} --output=type=image,push=false --platform linux/aarch64 -f ${{ steps.vars.outputs.DOCKERFILE }}
-      - name: tag single-arch image (aarch64-linux)
+      - name: Tag single-arch image (aarch64-linux)
         run: |
           docker buildx build ${{ steps.vars.outputs.SRC }}  --builder=container --cache-from=type=registry,ref=${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} --load --platform linux/aarch64 -f ${{ steps.vars.outputs.DOCKERFILE }} --tag ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }}
-      - name: test single-arch image (aarch64-linux)
+      - name: Test single-arch image (aarch64-linux)
         run: |
           docker run --platform linux/aarch64 --rm ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} /bin/sh -c 'true'
           docker run --platform linux/aarch64 --rm ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} ruby -e 'puts RUBY_DESCRIPTION'
           docker run --platform linux/aarch64 --rm ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} gem --version
           docker run --platform linux/aarch64 --rm ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} bundle --version
           docker run --platform linux/aarch64 --rm -v "${PWD}":"${PWD}" -w "${PWD}" ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} /bin/sh -c 'bundle install && bundle exec rake test'
       
-      # finally assemble multi-arch image for a combined push to the registry. this reruns docker build but because the layers are cached, it's fast
-      - name: log in to the container registry
+      # Assemble multi-arch image for a combined push to the registry
+      # 
+      # Docker build is rerun, but build is fast because the layers are already cached
+      - name: Log in to the container registry
         if: ${{ inputs.push }}
         run: |
           echo ${{ secrets.GITHUB_TOKEN }} | docker login ${{ env.REGISTRY }} -u ${{ github.actor }} --password-stdin
-      - name: Build multi-arch image (x86_64, aarch64)
+      - name: Build multi-arch image (x86-64, aarch64)
         if: ${{ inputs.push }}
         run: |
           docker buildx build ${{ steps.vars.outputs.SRC }} --builder=container --cache-from=type=registry,ref=${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }} --output=type=image,push=true --build-arg BUILDKIT_INLINE_CACHE=1 --platform linux/x86_64,linux/aarch64 -f ${{ steps.vars.outputs.DOCKERFILE }} --tag ${{ steps.vars.outputs.IMAGE }}:${{ steps.vars.outputs.TAG }}