From c57cf716afd139c6dd701664a63cc9ae32a01b45 Mon Sep 17 00:00:00 2001
From: Anonymous Maarten <anonymous.maarten@gmail.com>
Date: Sat, 31 Aug 2024 01:29:23 +0200
Subject: [PATCH] Document the SDL-specific custom ci commands

---
 .github/workflows/create-test-plan.py | 11 +++++++----
 .github/workflows/generic.yml         |  7 +++++++
 docs/README-contributing.md           | 10 ++++++++++
 3 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/create-test-plan.py b/.github/workflows/create-test-plan.py
index d7c286e15f..522ea54abd 100755
--- a/.github/workflows/create-test-plan.py
+++ b/.github/workflows/create-test-plan.py
@@ -158,6 +158,7 @@ class SharedLibType(Enum):
 @dataclasses.dataclass(slots=True)
 class JobDetails:
     name: str
+    key: str
     os: str
     platform: str
     artifact: str
@@ -221,6 +222,7 @@ class JobDetails:
     def to_workflow(self, enable_artifacts: bool) -> dict[str, str|bool]:
         data = {
             "name": self.name,
+            "key": self.key,
             "os": self.os,
             "container": self.container if self.container else "",
             "platform": self.platform,
@@ -293,9 +295,10 @@ def my_shlex_join(s):
     return " ".join(escape(s))
 
 
-def spec_to_job(spec: JobSpec, trackmem_symbol_names: bool) -> JobDetails:
+def spec_to_job(spec: JobSpec, key: str, trackmem_symbol_names: bool) -> JobDetails:
     job = JobDetails(
         name=spec.name,
+        key=key,
         os=spec.os.value,
         artifact=spec.artifact or "",
         container=spec.container or "",
@@ -723,9 +726,9 @@ def spec_to_job(spec: JobSpec, trackmem_symbol_names: bool) -> JobDetails:
     return job
 
 
-def spec_to_platform(spec: JobSpec, enable_artifacts: bool, trackmem_symbol_names: bool) -> dict[str, str|bool]:
+def spec_to_platform(spec: JobSpec, key: str, enable_artifacts: bool, trackmem_symbol_names: bool) -> dict[str, str|bool]:
     logger.info("spec=%r", spec)
-    job = spec_to_job(spec, trackmem_symbol_names=trackmem_symbol_names)
+    job = spec_to_job(spec, key=key, trackmem_symbol_names=trackmem_symbol_names)
     logger.info("job=%r", job)
     platform = job.to_workflow(enable_artifacts=enable_artifacts)
     logger.info("platform=%r", platform)
@@ -773,7 +776,7 @@ def main():
 
     all_level_platforms = {}
 
-    all_platforms = {k: spec_to_platform(spec, enable_artifacts=args.enable_artifacts, trackmem_symbol_names=args.trackmem_symbol_names) for k, spec in JOB_SPECS.items()}
+    all_platforms = {key: spec_to_platform(spec, key=key, enable_artifacts=args.enable_artifacts, trackmem_symbol_names=args.trackmem_symbol_names) for key, spec in JOB_SPECS.items()}
 
     for level_i, level_keys in enumerate(all_level_keys, 1):
         level_key = f"level{level_i}"
diff --git a/.github/workflows/generic.yml b/.github/workflows/generic.yml
index 14d11d405d..623017ac9b 100644
--- a/.github/workflows/generic.yml
+++ b/.github/workflows/generic.yml
@@ -34,6 +34,13 @@ jobs:
             ${{ (!matrix.platform.msys2-no-perl && format('{0}-perl', matrix.platform.msys2-env)) || '' }}
             ${{ matrix.platform.msys2-env }}-pkg-config
             ${{ matrix.platform.msys2-env }}-clang-tools-extra
+      - name: 'About this job'
+        run: |
+          echo "key=${{ matrix.platform.key }}"
+          echo "name=${{ matrix.platform.name }}"
+          echo "os=${{ matrix.platform.os }}"
+          echo ""
+          echo "Add [sdl-ci-filter ${{ matrix.platform.key }}] to your commit message to reduce the number of jobs."
       - uses: actions/checkout@v4
       - name: 'Set up ninja'
         if: ${{ matrix.platform.setup-ninja }}
diff --git a/docs/README-contributing.md b/docs/README-contributing.md
index 347f0f825a..e6435f787d 100644
--- a/docs/README-contributing.md
+++ b/docs/README-contributing.md
@@ -12,6 +12,7 @@ We appreciate your interest in contributing to SDL, this document will describe
     -   [Following the style guide](#following-the-style-guide)
     -   [Running the tests](#running-the-tests)
     -   [Opening a pull request](#opening-a-pull-request)
+    -   [Continuous integration](#continuous-integration)
 -   [Contributing to the documentation](#contributing-to-the-documentation)
     -   [Editing a function documentation](#editing-a-function-documentation)
     -   [Editing the wiki](#editing-the-wiki)
@@ -86,6 +87,15 @@ Tests allow you to verify if your changes did not break any behaviour, here are
 -   Fill out the pull request template.
 -   If any changes are requested, you can add new commits to your fork and they will be automatically added to the pull request.
 
+### Continuous integration
+
+For each push and/or pull request, GitHub Actions will try to build SDL and the test suite on most supported platforms.
+
+Its behaviour can be influenced slightly by including SDL-specific tags in your commit message:
+- `[sdl-ci-filter GLOB]` limits the platforms for which to run ci.
+- `[sdl-ci-artifacts]` forces SDL artifacts, which can then be downloaded from the summary page.
+- `[sdl-ci-trackmem-symbol-names]` makes sure the final report generated by `--trackmem` contains symbol names.
+
 ## Contributing to the documentation
 
 ### Editing a function documentation