[ci] Add/update docs for .buildkite dir and PR pipeline generator (el…

…astic#103936)

.buildkite/README.md

@@ -0,0 +1,41 @@
+# Elasticsearch CI Pipelines
+
+This directory contains pipeline definitions and scripts for running Elasticsearch CI on Buildkite.
+
+## Directory Structure
+
+- [pipelines](pipelines/) - pipeline definitions/yml
+- [scripts](scripts/) - scripts used by pipelines, inside steps
+- [hooks](hooks/) - [Buildkite hooks](https://buildkite.com/docs/agent/v3/hooks), where global env vars and secrets are set
+
+## Pipeline Definitions
+
+Pipelines are defined using YAML files residing in [pipelines](pipelines/). These are mostly static definitions that are used as-is, but there are a few dynamically-generated exceptions (see below).
+
+### Dynamically Generated Pipelines
+
+Pull request pipelines are generated dynamically based on labels, files changed, and other properties of pull requests.
+
+Non-pull request pipelines that include BWC version matrices must also be generated whenever the [list of BWC versions](../.ci/bwcVersions) is updated.
+
+#### Pull Request Pipelines
+
+Pull request pipelines are generated dynamically at CI time based on numerous properties of the pull request. See [scripts/pull-request](scripts/pull-request) for details.
+
+#### BWC Version Matrices
+
+For pipelines that include BWC version matrices, you will see one or more template files (e.g. [periodic.template.yml](pipelines/periodic.template.yml)) and a corresponding generated file (e.g. [periodic.yml](pipelines/periodic.yml)). The generated file is the one that is actually used by Buildkite.
+
+These files are updated by running:
+
+```bash
+./gradlew updateCIBwcVersions
+```
+
+This also runs automatically during release procedures.
+
+You should always make changes to the template files, and run the above command to update the generated files.
+
+## Node / TypeScript
+
+Node (technically `bun`), TypeScript, and related files are currently used to generate pipelines for pull request CI. See [scripts/pull-request](scripts/pull-request) for details.

.buildkite/package.json

@@ -1,6 +1,5 @@
 {
   "name": "buildkite-pipelines",
-  "module": "index.ts",
   "type": "module",
   "devDependencies": {
     "@types/node": "^20.6.0",

.buildkite/scripts/pull-request/README.md

@@ -6,12 +6,7 @@ Each time a pull request build is triggered, such as via commit or comment, we u
 
 The generator handles the following:
 
-  - `allow-labels` - only trigger a step if the PR has one of these labels
-  - `skip-labels` - don't trigger the step if the PR has one of these labels
-  - `excluded-regions` - don't trigger the step if **all** of the changes in the PR match these paths/regexes
-  - `included-regions` - trigger the step if **all** of the changes in the PR match these paths/regexes
-  - `trigger-phrase` - trigger this step, and ignore all other steps, if the build was triggered by a comment and that comment matches this regex
-    - Note that each step has an automatic phrase of `.*run\\W+elasticsearch-ci/<step-name>.*`
+  - Various configurations for filtering/activating steps based on labels, changed files, etc. See below.
   - Replacing `$SNAPSHOT_BWC_VERSIONS` in pipelines with an array of versions from `.ci/snapshotBwcVersions`
   - Duplicating any step with `bwc_template: true` for each BWC version in `.ci/bwcVersions`
 
@@ -21,18 +16,75 @@ The generator handles the following:
 
 Pipelines are in [`.buildkite/pipelines`](../../pipelines/pull-request). They are automatically picked up and given a name based on their filename.
 
-
 ## Setup
 
 - [Install bun](https://bun.sh/)
   - `npm install -g bun` will work if you already have `npm`
 - `cd .buildkite; bun install` to install dependencies
 
-## Run tests
+## Testing
+
+Testing the pipeline generator is done mostly using snapshot tests, which generate pipeline objects using the pipeline configurations in `mocks/pipelines` and then compare them to previously-generated snapshots in `__snapshots__` to confirm that they are correct.
+
+The mock pipeline configurations should, therefore, try to cover all of the various features of the generator (allow-labels, skip-labels, etc).
+
+Snapshots are generated/managed automatically whenever you create a new test that has a snapshot test condition. These are very similar to Jest snapshots.
+
+### Run tests
 
 ```bash
 cd .buildkite
 bun test
 ```
 
 If you need to regenerate the snapshots, run `bun test --update-snapshots`.
+
+## Pipeline Configuration
+
+The `config:` property at the top of pipelines inside `.buildkite/pipelines/pull-request` is a custom property used by our pipeline generator. It is not used by Buildkite.
+
+All of the pipelines in this directory are evaluated whenever CI for a pull request is started, and the steps are filtered and combined into one pipeline based on the properties in `config:` and the state of the pull request.
+
+The various configurations available mirror what we were using in our Jenkins pipelines.
+
+### Config Properties
+
+#### `allow-labels`
+
+- Type: `string|string[]`
+- Example: `["test-full-bwc"]`
+
+Only trigger a step if the PR has one of these labels.
+
+#### `skip-labels`
+
+- Type: `string|string[]`
+- Example: `>test-mute`
+
+Don't trigger the step if the PR has one of these labels.
+
+#### `excluded-regions`
+
+- Type: `string|string[]` - must be JavaScript regexes
+- Example: `["^docs/.*", "^x-pack/docs/.*"]`
+
+Exclude the pipeline if all of the changed files in the PR match at least one regex. E.g. for the example above, don't run the step if all of the changed files are docs changes.
+
+#### `included-regions`
+
+- Type: `string|string[]` - must be JavaScript regexes
+- Example: `["^docs/.*", "^x-pack/docs/.*"]`
+
+Only include the pipeline if all of the changed files in the PR match at least one regex. E.g. for the example above, only run the step if all of the changed files are docs changes.
+
+This is particularly useful for having a step that only runs, for example, when all of the other steps get filtered out because of the `excluded-regions` property.
+
+#### `trigger-phrase`
+
+- Type: `string` - must be a JavaScript regex
+- Example: `"^run\\W+elasticsearch-ci/test-full-bwc.*"`
+- Default: `.*run\\W+elasticsearch-ci/<step-name>.*` (`<step-name>` is generated from the filename of the yml file).
+
+Trigger this step, and ignore all other steps, if the build was triggered by a comment and that comment matches this regex.
+
+Note that the entire build itself is triggered via [`.buildkite/pull-requests.json`](../pull-requests.json). So, a comment has to first match the trigger configured there.