change(release): Make the latest tag point to the production build, rather than the build with experimental features

.github/workflows/ci-unit-tests-os.yml

@@ -51,7 +51,6 @@ on:
       - '**/clippy.toml'
       # workflow definitions
       - '.github/workflows/ci-unit-tests-os.yml'
-      - '.github/workflows/sub-build-docker-image.yml'
 
 env:
   CARGO_INCREMENTAL: ${{ vars.CARGO_INCREMENTAL }}

.github/workflows/release-binaries.yml

@@ -18,29 +18,31 @@ jobs:
   # Each time this workflow is executed, a build will be triggered to create a new image
   # with the corresponding tags using information from git
 
-  # The image will be named `zebra:<semver>`
-  build:
-    name: Build Release Docker
+  # The image will be named `zebra:<semver>.experimental`
+  build-experimental:
+    name: Build Experimental Features Release Docker
     uses: ./.github/workflows/sub-build-docker-image.yml
     with:
       dockerfile_path: ./docker/Dockerfile
       dockerfile_target: runtime
       image_name: zebra
-      features: ${{ vars.RUST_PROD_FEATURES }}
+      tag_suffix: .experimental
+      features: ${{ format('{0} {1}', vars.RUST_PROD_FEATURES, vars.RUST_EXPERIMENTAL_FEATURES) }}
       rust_log: ${{ vars.RUST_LOG }}
     # This step needs access to Docker Hub secrets to run successfully
     secrets: inherit
 
-  # The image will be named `zebra:<semver>.experimental`
-  build-experimental:
-    name: Build Experimental Features Release Docker
+  # The image will be named `zebra:<semver>`
+  # It should be built last, so overlapping tags point to the production build, not the experimental build.
+  build:
+    name: Build Release Docker
     uses: ./.github/workflows/sub-build-docker-image.yml
     with:
       dockerfile_path: ./docker/Dockerfile
       dockerfile_target: runtime
       image_name: zebra
-      tag_suffix: .experimental
-      features: ${{ format('{0} {1}', vars.RUST_PROD_FEATURES, vars.RUST_EXPERIMENTAL_FEATURES) }}
+      latest_tag: true
+      features: ${{ vars.RUST_PROD_FEATURES }}
       rust_log: ${{ vars.RUST_LOG }}
     # This step needs access to Docker Hub secrets to run successfully
     secrets: inherit

.github/workflows/sub-build-docker-image.yml

@@ -33,6 +33,10 @@ on:
       test_features:
         required: false
         type: string
+      latest_tag:
+        required: false
+        type: boolean
+        default: false
       tag_suffix:
         required: false
         type: string
@@ -88,19 +92,30 @@ jobs:
           # appends inputs.tag_suffix to image tags/names
           flavor: |
             suffix=${{ inputs.tag_suffix }}
+            latest=${{ inputs.latest_tag }}
           # generate Docker tags based on the following events/attributes
           tags: |
-            type=schedule
-            # semver and ref,tag automatically add a "latest" tag, but only on stable releases
+            # These DockerHub release tags support the following use cases:
+            # - `1.x.y`: always use the exact version, don't automatically upgrade
+            # - `sha-zzzzzz`: always use the exact commit (the same as `1.x.y`, but also used in CI and production image tests)
+            #
+            # Stopping publishing these tags is a breaking change for these use cases:
+            # - `latest`: always use the latest Zebra release when you pull or update
+            # - `1`: use the latest Zebra release, but require manual intervention for the next network upgrade
+            # - `1.x`: update to bug fix releases, but don't add any new features or incompatibilities
+            #
+            # semver automatically adds a "latest" tag, but only on stable releases
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
-            type=ref,event=tag
-            type=ref,event=branch
-            type=ref,event=pr
+            # DockerHub release and CI tags.
+            # This tag makes sure tests are using exactly the right image, even when multiple PRs run at the same time.
             type=sha
-            # edge is the latest commit on the default branch.
-            type=edge,enable={{is_default_branch}}
+            # These CI-only tags support CI on PRs, the main branch, and scheduled full syncs. 
+            # These tags do not appear on DockerHub, because DockerHub images are only published on the release event.
+            type=ref,event=pr
+            type=ref,event=branch
+            type=schedule
 
       # Setup Docker Buildx to allow use of docker cache layers from GH
       - name: Set up Docker Buildx