📖 Reference new build system docs (#22226)

* Reference new build system docs

* Add references to qa engine

airbyte-integrations/builds-readme.md

@@ -1,6 +1,8 @@
-# How is the builds page generated? 
-[This github action](https://github.com/airbytehq/airbyte/blob/master/.github/workflows/connector_integration_tests.yml) runs once a day. 
-It triggers builds for all connectors. The result of this build is persisted on an S3 bucket in our AWS dev environment. 
-Ask for access rights from the Airbyte team if you need it to access the environment. This S3 bucket is hooked up to a CDN, AWS CloudFront. 
+# How is the builds page generated?
+[This github action](https://github.com/airbytehq/airbyte/blob/master/.github/workflows/connector_integration_tests.yml) runs once a day.
+It triggers builds for all connectors. The result of this build is persisted on an S3 bucket in our AWS dev environment.
+Ask for access rights from the Airbyte team if you need it to access the environment. This S3 bucket is hooked up to a CDN, AWS CloudFront.
 Then, [this Github action](https://github.com/airbytehq/airbyte/blob/master/.github/workflows/build-report.yml) reads from Cloudfront to send a daily
-Slack message informing us of the build status of any connectors in need of attention. 
+Slack message informing us of the build status of any connectors in need of attention.
+
+To understand this system in more depth read the documentation here: https://internal-docs.airbyte.io/Generated-Reports/Build-Status-Reports

airbyte-integrations/builds.md

@@ -1,4 +1,5 @@
 # Build statuses
+<!-- Docs on how this system works: https://internal-docs.airbyte.io/Generated-Reports/Build-Status-Reports -->
 
 # Sources
 

tools/bin/build_report.py

@@ -3,8 +3,13 @@
 #
 
 """
+Report Connector Build Status to Slack
+
 All invocations of this script must be run from the Airbyte repository root.
 
+BEFORE RUNNING THIS SCRIPT:
+- Ensure you have read the documentation on how this system works: https://internal-docs.airbyte.io/Generated-Reports/Build-Status-Reports
+
 To Run tests:
 pytest ./tools/bin/build_report.py
 

tools/ci_connector_ops/ci_connector_ops/qa_engine/inputs.py

@@ -33,6 +33,10 @@ def from_string(cls, string_value: Optional[str]) -> "BUILD_STATUSES":
 
 
 def get_connector_build_output_url(connector_technical_name: str, connector_version: str) -> str:
+    """
+    Get the connector build output url.
+    Documentation of the larger build output system can be found here: https://internal-docs.airbyte.io/Generated-Reports/Build-Status-Reports
+    """
     return f"{CONNECTOR_BUILD_OUTPUT_URL}/{connector_technical_name}/version-{connector_version}.json"
 
 def fetch_latest_build_status_for_connector_version(connector_technical_name: str, connector_version: str) ->BUILD_STATUSES:

tools/status/report.sh

@@ -1,5 +1,9 @@
 #!/usr/bin/env bash
 
+# This script is used to report the status of a connector build to S3.
+# BEFORE RUNNING THIS SCRIPT:
+#   - Ensure you have read the documentation on how this system works: https://internal-docs.airbyte.io/Generated-Reports/Build-Status-Reports
+
 set -e
 
 . tools/lib/lib.sh