Merge pull request #9923 from harness/dewan-ci15398

Add details from CI-15398

Author: dewan-ahmed

Diff for: docs/continuous-integration/shared/enhanced-output-variables.md

@@ -0,0 +1,72 @@
+---
+title: Enhanced Output Variable Handling in CI Steps
+description: Learn about the new enhancements in CI steps, including multiline output variable support, improved output handling, JSON preservation, and updated best practices.
+sidebar_position: 50
+---
+<details>
+<summary>Early access feature: Multi-line Output Variables</summary>
+- **Multiline Output Variables**: CI steps support multiline output variables, including special characters such as `\n`, `\t`, `\r`, `\b`, maintaining shell-like behavior.  
+- **Complete Output Support**: Output variables support both output secrets and output strings.  
+- **JSON Preservation**: JSON data can be passed as-is without automatic minification.  
+- **Increased Output Variable Capacity**: The maximum output variable size is approximately **131,072 characters**, up from 65,536.  
+
+#### Technical Limitations  
+- The **maximum size** of output variables is constrained by the operating system's `ARG_MAX` parameter, which limits command line arguments and environment variables.  
+- Exceeding this limit will result in the error:  
+  ```shell
+  fork/exec /bin/sh: argument list too long
+  ```  
+- This limitation is imposed by the operating system, not by the implementation of this feature.  
+
+#### Behavior Changes: Current vs. New  
+The following table outlines changes in how special characters are handled in output variables:  
+
+| Command             | Current Behavior | New Behavior |
+|---------------------|-----------------|-------------|
+| `export out="\b"`  | `"\b"`           | Backspace   |
+| `export out="\f"`  | `"\f"`           | Form feed   |
+| `export out="\n"`  | `"\n"`           | Newline character |
+| `export out="\r"`  | `"\r"`           | Carriage return |
+| `export out="\t"`  | `"\t"`           | Tab character |
+| `export out="\v"`  | `"\v"`           | Vertical tab |
+
+#### Best Practices  
+
+**Python Shell**  
+For multiline strings in Python, use triple quotes (`"""` or `'''`) to maintain formatting properly.  
+
+**Step 1:** Export an output variable:  
+```python
+out = """line1,
+line2,
+line3"""
+os.environ["out"] = out
+```  
+
+**Step 2:** Read the output variable:  
+```python
+str_value = """<+execution.steps.Step_name.output.outputVariables.out>"""
+```  
+
+**PowerShell**  
+For PowerShell, use the `@"..."@` syntax to handle multiline strings effectively.  
+
+**Step 1:** Export an output variable:  
+```powershell
+$out=@"
+line1,
+line2,
+line3
+"@
+$env:out = $out
+```  
+
+**Step 2:** Read the output variable:  
+```powershell
+$str_value = @"
+<+execution.steps.Step_name.output.outputVariables.out>
+"@
+```  
+
+These best practices ensure proper handling of multiline strings across different environments while maintaining consistency in CI workflows.
+</details>

Diff for: docs/continuous-integration/shared/output-var.md

@@ -33,7 +33,7 @@ In the following YAML example, step `alpha` exports an output variable called `m
 
 * **Secrets in output variables exposed in logs:** If an output variable value contains a secret, be aware that the secret will be visible in the [build details](/docs/continuous-integration/use-ci/viewing-builds.md). Such secrets are visible on the **Output** tab of the step where the output variable originates and in the build logs for any later steps that reference that variable. For information about best practices for using secrets in pipelines, go to the [Secrets documentation](/docs/category/secrets).
 * **64KB length limit:** If an output variable's length is greater than 64KB, steps can fail or truncate the output. If you need to export large amounts of data, consider [uploading artifacts](/docs/continuous-integration/use-ci/build-and-upload-artifacts/build-and-upload-an-artifact#upload-artifacts) or [exporting artifacts by email](/docs/continuous-integration/use-ci/build-and-upload-artifacts/drone-email-plugin.md).
-* **Single line limit:** Output variables don't support multi-line output. Content after the first line is truncated. If you need to export multi-line data, consider [uploading artifacts](/docs/continuous-integration/use-ci/build-and-upload-artifacts/build-and-upload-an-artifact#upload-artifacts) or [exporting artifacts by email](/docs/continuous-integration/use-ci/build-and-upload-artifacts/drone-email-plugin.md).
+* **Single line limit:** By default, output variables are limited to a single line. To enable multi-line output variables, use the feature flag `CI_NEW_VERSION_GODOTENV`. To export multi-line data, you can also consider [uploading artifacts](/docs/continuous-integration/use-ci/build-and-upload-artifacts/build-and-upload-an-artifact#upload-artifacts) or [exporting artifacts by email](/docs/continuous-integration/use-ci/build-and-upload-artifacts/drone-email-plugin.md).
 * **Exit Codes:** In the event that an exit code is defined and set in the script, the output variables will not be available as an output from the step because it is a "forced" exit.  The output from the step will be empty which can be desired depending on the situation.
 This includes `exit 0` definitions.  Therefore, customers should not define an **exit 0 situation**, as "completing the script" to the end is what is expected as a "healthy" completion of the script.  
 :::

Diff for: docs/continuous-integration/use-ci/run-step-settings.md

@@ -14,6 +14,7 @@ redirect_from:
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import EnhancedOutVar from '/docs/continuous-integration/shared/enhanced-output-variables.md';
 import OutVar from '/docs/continuous-integration/shared/output-var.md';
 
 You can use a **Run** step to run commands or scripts in a CI pipeline. Here are some examples of different ways you can use **Run** steps.
@@ -455,7 +456,7 @@ Variable values can be [fixed values, runtime inputs, or expressions](/docs/plat
 ### Output Variables
 
 <OutVar />
-
+<EnhancedOutVar/>
 <!--<details>
 <summary>Export output variables to stage or pipeline variables</summary>
 

Diff for: docs/continuous-integration/use-ci/run-tests/tests-v2.md

@@ -5,6 +5,7 @@ sidebar_position: 3
 ---
 
 import OutVar from '/docs/continuous-integration/shared/output-var.md';
+import EnhancedOutVar from '/docs/continuous-integration/shared/enhanced-output-variables.md';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
@@ -167,6 +168,8 @@ When using **.Net**, make sure to enable log reporting when running the tests, e
 
 <OutVar />
 
+<EnhancedOutVar/>
+
 ### Environment Variables
 
 You can inject environment variables into the step container and use them in the step's commands. You must input a **Name** and **Value** for each variable.