From c57cf716afd139c6dd701664a63cc9ae32a01b45 Mon Sep 17 00:00:00 2001
From: Anonymous Maarten <[EMAIL REDACTED]>
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 d7c286e15f9ec..522ea54abd43c 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 escape(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 tf(b):
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 14d11d405d850..623017ac9bb99 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 347f0f825a39a..e6435f787d0e3 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