docs: old version release instructions (#1105)

Author: MikeMcC399

CONTRIBUTING.md

@@ -47,9 +47,22 @@ docker compose run test-factory-all-included
 
 #### Automatic
 
-To publish a new image for `factory`, `included`, `browsers`, and `base`, open a PR with the desired version(s) updated in the `factory/.env` file. Once the PR is merged into master, the corresponding images will be pushed to dockerhub via an automated script run in CI. Please check that the CI jobs pass after merge.
+##### New versions
 
-In general, `factory/.env` master should contain the latest versions we officially support. If you need to release an older version please modify `circle.yml` to push releases from a feature branch instead of setting the version in master to older versions.
+To publish a new image for `factory`, `base`, `browsers`, and `included`, open a PR with the desired version(s) updated in the [factory/.env](./factory/.env) file. Once the PR is merged into the `master` branch, the corresponding images will be pushed to Docker Hub via an automated script run in CI. Please check that the CI jobs pass after merge.
+
+##### Older versions
+
+>Note: Assistance from a member of the Cypress org is required for this process
+
+In general, [factory/.env](./factory/.env) in the `master` branch should contain the latest versions we officially support. If you need to release an older version, do not modify contents in the `master` branch. Instead, carry out the following steps:
+
+1. Create a feature branch in the form `<cypress-version>-node-<node.js version>-publish`, for example `13.11.0-node-18.20.3-publish`, branched from the `master` branch. If you are not a member of the Cypress org, make a request via a new issue to create a feature branch.
+2. Modify [factory/.env](./factory/.env) with the desired versions. Do not modify the `FACTORY_VERSION`. No new `cypress/factory` image should be published with this process.
+3. Modify [factory/docker-compose.yml](./factory/docker-compose.yml) to comment out the creation of `latest` tags. Comment out the `cypress/included` `INCLUDED_IMAGE_SHORT_TAG` to also prevent this tag from being created. This step is essential to avoid related tags of existing released images being moved back to point to older images.
+4. Modify [circle.yml](circle.yml) to push releases from the feature branch.
+5. Open a PR which targets the feature branch.
+6. After PR merge, check Docker Hub and the associated new image(s).
 
 #### Manual
 

circle.yml

@@ -1,5 +1,10 @@
 # info on building Docker images on Circle
 # https://circleci.com/docs/2.0/building-docker-images/
+
+## If you wish to release an older Docker image, do not modify this file in the master branch.
+## Follow the instructions in the CONTRIBUTING document and work instead in a feature branch.
+## Modify the push jobs below to be triggered on the feature branch, not the master branch.
+
 version: 2.1
 
 orbs:
@@ -328,7 +333,11 @@ workflows:
                 context: test-runner:docker-push
                 filters:
                     branches:
-                        only:  # only branches matching the below regex filters will run
+                        only:
+                        # Only branches matching the below regex filters will run
+                        # Change to a feature branch such as <cypress-version>-node-<node.js version>-publish
+                        # if publishing an old version
+                        # This job must run because the base, browsers and included jobs depend on it
                             - master
                 requires:
                     - factory
@@ -341,7 +350,10 @@ workflows:
                 context: test-runner:docker-push
                 filters:
                     branches:
-                        only:  # only branches matching the below regex filters will run
+                        only:
+                        # Only branches matching the below regex filters will run
+                        # Change to a feature branch such as <cypress-version>-node-<node.js version>-publish
+                        # if publishing an old version
                             - master
                 requires:
                     - "Push Factory Image"
@@ -353,7 +365,10 @@ workflows:
                 context: test-runner:docker-push
                 filters:
                     branches:
-                        only:  # only branches matching the below regex filters will run
+                        only:
+                        # Only branches matching the below regex filters will run
+                        # Change to a feature branch such as <cypress-version>-node-<node.js version>-publish
+                        # if publishing an old version
                             - master
                 requires:
                     - "Push Factory Image"
@@ -365,7 +380,10 @@ workflows:
                 context: test-runner:docker-push
                 filters:
                     branches:
-                        only:  # only branches matching the below regex filters will run
+                        only:
+                        # Only branches matching the below regex filters will run
+                        # Change to a feature branch such as <cypress-version>-node-<node.js version>-publish
+                        # if publishing an old version
                             - master
                 requires:
                     - "Push Factory Image"

factory/.env

@@ -1,8 +1,7 @@
-## This env represents the latest versions cyrpess supports. If you wish to push an older docker image,
-## please modify circle ci to release a one off branch instead of merging old versions to this file in master.
-## For example, one could modify the filters on the push jobs.
-## https://github.com/cypress-io/cypress-docker-images/blob/matth/docker-factory/circle.yml#L271-L274
-## to setup a one off branch and create at a PR to it to release resulting images.
+## This env file represents the latest versions Cypress supports.
+##
+## If you wish to release an older Docker image, do not modify this file in the master branch.
+## Follow the instructions in the CONTRIBUTING document and work instead in a feature branch.
 
 # The debian image the factory is based on
 BASE_IMAGE='debian:12-slim'

factory/docker-compose.yml

@@ -1,5 +1,10 @@
 # REPO_PREFIX is used in CI to deploy to other docker registries than dockerhub.
 
+## If you wish to release an older Docker image, do not modify this file in the master branch.
+## Follow the instructions in the CONTRIBUTING document and work instead in a feature branch.
+## Comment out the tags entries for latest tags below so that no latest tag is created.
+## Comment out the INCLUDED_IMAGE_SHORT_TAG so that this tag is not reassigned to an older version.
+
 services:
 
   factory:
@@ -12,7 +17,7 @@ services:
         BASE_IMAGE: ${BASE_IMAGE}
         FACTORY_DEFAULT_NODE_VERSION: ${FACTORY_DEFAULT_NODE_VERSION}
       tags:
-       - ${REPO_PREFIX-}cypress/factory:latest
+       - ${REPO_PREFIX-}cypress/factory:latest  # comment out for release of older version
        - ${REPO_PREFIX-}cypress/factory:${FACTORY_VERSION}
     command: node -v
 
@@ -31,8 +36,8 @@ services:
         YARN_VERSION: ${YARN_VERSION}
         # WEBKIT_VERSION: ${WEBKIT_VERSION}
       tags:
-       - ${REPO_PREFIX-}cypress/included:latest
-       - ${REPO_PREFIX-}cypress/included:${INCLUDED_IMAGE_SHORT_TAG}
+       - ${REPO_PREFIX-}cypress/included:latest # comment out for release of older version
+       - ${REPO_PREFIX-}cypress/included:${INCLUDED_IMAGE_SHORT_TAG}  # comment out for release of older version
        - ${REPO_PREFIX-}cypress/included:${INCLUDED_IMAGE_TAG}
     command: node -v
 
@@ -49,7 +54,7 @@ services:
         FIREFOX_VERSION: ${FIREFOX_VERSION}
         EDGE_VERSION: ${EDGE_VERSION}
       tags:
-       - ${REPO_PREFIX-}cypress/browsers:latest
+       - ${REPO_PREFIX-}cypress/browsers:latest # comment out for release of older version
        - ${REPO_PREFIX-}cypress/browsers:${BROWSERS_IMAGE_TAG}
     command: node -v
 
@@ -63,7 +68,7 @@ services:
         FACTORY_VERSION: ${FACTORY_VERSION}
         YARN_VERSION: ${YARN_VERSION}
       tags:
-       - ${REPO_PREFIX-}cypress/base:latest
+       - ${REPO_PREFIX-}cypress/base:latest # comment out for release of older version
        - ${REPO_PREFIX-}cypress/base:${BASE_IMAGE_TAG}
     command: node -v