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 }}