Add possibility to apply a commit with patch to docs when publishing

You can specify commit hash to apply when you build documentation.
This allows to regenerate past version of the documentation by
checking out the exact version tag that was used back then and
applying the commit hash with fixes.

This might help in fixing issues like
#53646

Author: potiuk

.github/workflows/publish-docs-to-s3.yml

@@ -60,6 +60,10 @@ on:  # yamllint disable-line rule:truthy
         required: false
         description: "Override the Airflow Version to use for the docs build"
         type: string
+      apply-commits:
+        required: false
+        description: "Optionally apply commit hashes before building - to patch the docs (coma separated)"
+        type: string
 permissions:
   contents: read
 jobs:
@@ -162,6 +166,7 @@ jobs:
       INCLUDE_SUCCESS_OUTPUTS: false
       VERBOSE: "true"
       EXTRA_BUILD_OPTIONS: ${{ needs.build-info.outputs.extra-build-options }}
+      APPLY_COMMITS: ${{ inputs.apply-commits || '' }}
     steps:
       - name: "Cleanup repo"
         shell: bash
@@ -184,6 +189,20 @@ jobs:
           ref: ${{ inputs.ref }}
           fetch-depth: 0
           fetch-tags: true
+      - name: "Apply patch commits if provided"
+        run: |
+          if [[ "${APPLY_COMMITS}" != "" ]]; then
+            echo "Applying commits ${APPLY_COMMIT} to the docs"
+            # Split APPLY_COMMITS by comma and apply each commit
+            IFS=',' read -ra COMMIT_ARRAY <<< "${APPLY_COMMITS}"
+            for APPLY_COMMIT in "${COMMIT_ARRAY[@]}"; do
+              echo "Applying commit ${APPLY_COMMIT}"
+              git fetch origin "${APPLY_COMMIT}"
+              git cherry-pick "${APPLY_COMMIT}"
+            done
+          else
+            echo "No commits provided to apply, skipping."
+          fi
       - name: "Install Breeze from the ${{ inputs.ref }} reference"
         uses: ./.github/actions/breeze
         with:

dev/README_RELEASE_AIRFLOW.md

@@ -411,6 +411,23 @@ Other available parameters can be found with:
 breeze workflow-run publish-docs --help
 ```
 
+In case you publish the documentation from branch, you can specify `--airflow-version` and `--airflow-base-version`
+parameters to specify which version of airflow you want to build the documentation for - as it cannot
+be automatically derived from tag name. Normally both are automatically derived from the tag name.
+
+One of the interesting features of publishing this way is that you can also rebuild historical version of
+the documentation with patches applied to the documentation (if they can be applied cleanly).
+
+Yoy should specify the `--apply-commits` parameter with the list of commits you want to apply
+separated by commas and the workflow will apply those commits to the documentation before
+building it. Example:
+
+```shell script
+breeze workflow-run publish-docs --ref 3.0.3 --site-env staging \
+  --apply-commits 4ae273cbedec66c87dc40218c7a94863390a380d,e61e9618bdd6be8213d277b1427f67079fcb1d9b \
+  apache-airflow docker-stack task-sdk
+```
+
 ### Manually using GitHub Actions
 
 There are two steps to publish the documentation:

dev/README_RELEASE_PROVIDERS.md

@@ -522,6 +522,18 @@ The `--ref` parameter should be the tag of the release candidate you are publish
 The `--site-env` parameter should be set to `staging` for pre-release versions or `live` for final releases. the default option is `auto`
 if the tag is rc it publishes to `staging` bucket, otherwise it publishes to `live` bucket.
 
+One of the interesting features of publishing this way is that you can also rebuild historical version of
+the documentation with patches applied to the documentation (if they can be applied cleanly).
+
+Yoy should specify the `--apply-commits` parameter with the list of commits you want to apply
+separated by commas and the workflow will apply those commits to the documentation before
+building it. Example:
+
+```shell script
+breeze workflow-run publish-docs --ref providers-apache-hive/9.0.0 --site-env live \
+  --apply-commits 4ae273cbedec66c87dc40218c7a94863390a380d hive
+```
+
 Other available parameters can be found with:
 
 ```shell

dev/breeze/doc/images/output_workflow-run_publish-docs.svg

@@ -1 +1 @@
-9d78a242ea07f4467d68d6eb769c6e57
+d0677b79afb4dba327d26a35c97455b3

dev/breeze/doc/images/output_workflow-run_publish-docs.txt

@@ -89,6 +89,13 @@ def workflow_run():
     default=None,
     type=str,
 )
+@click.option(
+    "--apply-commits",
+    help="Apply commits before building the docs - for example to patch fixes "
+    "to the docs (comma separated list of commits). ",
+    default=None,
+    type=str,
+)
 @argument_doc_packages
 def workflow_run_publish(
     ref: str,
@@ -99,6 +106,7 @@ def workflow_run_publish(
     skip_write_to_stable_folder: bool = False,
     airflow_version: str | None = None,
     airflow_base_version: str | None = None,
+    apply_commits: str | None = None,
 ):
     if os.environ.get("GITHUB_TOKEN", ""):
         get_console().print("\n[warning]Your authentication will use GITHUB_TOKEN environment variable.")
@@ -165,6 +173,7 @@ def workflow_run_publish(
         "exclude-docs": exclude_docs,
         "skip-write-to-stable-folder": skip_write_to_stable_folder,
         "build-sboms": "true" if "apache-airflow" in doc_packages else "false",
+        "apply-commits": apply_commits if apply_commits else "",
     }
 
     if airflow_version:

dev/breeze/src/airflow_breeze/commands/workflow_commands.py

@@ -28,6 +28,7 @@
             "options": [
                 "--ref",
                 "--skip-tag-validation",
+                "--apply-commits",
             ],
         },
         {