From dcb764b1d3fc043c9031ea9cd93c386f5bf10a5b Mon Sep 17 00:00:00 2001
From: godofredoc <godofredoc@google.com>
Date: Thu, 8 Jun 2023 17:43:12 -0700
Subject: [PATCH] Document the use of realm in archives. (flutter/engine#42682)

Add docs for realm propery in the archives of build configuration files.

Bug: https://github.com/flutter/flutter/issues/126121

[C++, Objective-C, Java style guides]: https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style
---
 engine/src/flutter/ci/builders/README.md | 25 ++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/engine/src/flutter/ci/builders/README.md b/engine/src/flutter/ci/builders/README.md
index 8a9a3841720..eb715a8c5b1 100644
--- a/engine/src/flutter/ci/builders/README.md
+++ b/engine/src/flutter/ci/builders/README.md
@@ -150,7 +150,8 @@ configuration.
   "type": "gcs",
   "include_paths": [
      "out/host_debug/zip_archives/linux-x64/artifacts.zip"
-  ]
+  ],
+  "realm": "production"
 }
 ```
 
@@ -176,6 +177,10 @@ cleanups. Gcs is expected for any artifacts being consumed by the flutter tool.
 given destination.
 * **cas_archive** - a boolean value indicating whether the build output will
 be archived to CAS or not. The default value is true.
+* **realm** - a string value of either `production` or `experimental`
+where production means the artifact will be uploaded to the location expected
+by the flutter tool and experimental will add an `experimental` prefix to the
+path to avoid interfering with production artifacts.
 
 #### Drone\_dimensions
 
@@ -508,19 +513,27 @@ new artifacts combining outputs of multiple sub-builds.
 ### Global Archives
 
 The archives component provides instructions to upload the artifacts generated
-by the global generators. Is a list of dictionaries with two keys: `source` and
-`destination`. `source` is a path relative to the checkout repository and
-`destination` is a relative path to &lt;bucket>/flutter/&lt;commit>.
+by the global generators. Is a list of dictionaries with three keys: `source` and
+`destination`, and `realm`. `source` is a path relative to the checkout repository,
+`destination` is a relative path to &lt;bucket>/flutter/&lt;commit>, and `realm` is
+a string with either `production` or `experimental` value.
+
+The realm value is used to build the destination path of the artifacts.
+`production` will upload the artifacts to the location expected by the flutter
+tool and `experimental` will add experimental as a prefix to the path to avoid
+interfering with the production artifacts.
 
 ```json
 "archives": [
     {
         "source": "out/debug/artifacts.zip",
-        "destination": "ios/artifacts.zip"
+        "destination": "ios/artifacts.zip",
+        "realm": "production"
     },
     {
         "source": "out/debug/ios-objcdoc.zip",
-        "destination": "ios-objcdoc.zip"
+        "destination": "ios-objcdoc.zip",
+        "realm": "experimental"
     }
 ]
 ```