Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions .agents/rules/bazelci.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
trigger: glob
description: BazelCI presubmit.yml flag conventions
globs: ".bazelci/**"
---

# BazelCI Presubmit Config Rule

* Write `build_flags` and `test_flags` as YAML mappings with `? "--flag"`
keys, not as lists. Don't put matrix placeholders (`${{ }}`) in those keys;
bazelci.py doesn't expand them in mapping keys.
* To give a task the shared flags plus its own, merge the anchor instead of
copying flags: `<<: *reusable_config_build_flags` or
`<<: *reusable_config_test_flags`, then add the task's keys. A task's own
`build_flags` or `test_flags` replaces the inherited mapping entirely.
* To change a merged flag, such as a tag filter, list it again: Bazel uses
the last value.
* Pass build-configuration flags, such as `--config=ci`, to both build and
test, so `bazel test` reuses the build's analysis cache.
* Only the root `.bazelrc` defines `--config=ci`. Tasks with a
`working_directory` can't use it.
* When a task has several `<<:` keys, later anchors win for the same key;
e.g. the workspace anchors replace `reusable_config`'s flags. In the list
form, `<<: [*a, *b]`, the first anchor wins.
* After editing, run
`bazel test --config=fast-tests //tests/bazelci:presubmit_test`. To
review how each task's flags changed, run
`bazel run //dev/bazelci:diff_presubmit_flags`.
5 changes: 5 additions & 0 deletions .bazelci/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
filegroup(
name = "presubmit_yml",
srcs = ["presubmit.yml"],
visibility = ["//:__subpackages__"],
)
18 changes: 18 additions & 0 deletions dev/bazelci/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
load("//python:py_binary.bzl", "py_binary")
load("//python:py_library.bzl", "py_library")

package(default_visibility = ["//:__subpackages__"])

py_library(
name = "presubmit_flags",
srcs = ["presubmit_flags.py"],
imports = ["../.."],
deps = ["@pypi//pyyaml"],
)

py_binary(
name = "diff_presubmit_flags",
srcs = ["diff_presubmit_flags.py"],
imports = ["../.."],
deps = [":presubmit_flags"],
)
82 changes: 82 additions & 0 deletions dev/bazelci/diff_presubmit_flags.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
"""Shows how a presubmit.yml change alters each BazelCI task's flags.

Usage:
bazel run //dev/bazelci:diff_presubmit_flags
bazel run //dev/bazelci:diff_presubmit_flags -- --base=HEAD~1
bazel run //dev/bazelci:diff_presubmit_flags -- --flag=--config=ci

It reads `.bazelci/presubmit.yml` from the workspace and, through `git show`,
from the `--base` ref. For each task, it prints the `build_flags` and
`test_flags` that were added or removed, as BazelCI passes them to Bazel after
resolving YAML merges. With `--flag`, it instead lists the tasks in the
workspace's presubmit.yml that pass that flag.
"""

from __future__ import annotations

import argparse
import os
import subprocess
import sys
from pathlib import Path

from dev.bazelci import presubmit_flags


def _git_show(workspace: Path, spec: str) -> str:
try:
result = subprocess.run(
["git", "show", spec],
cwd=workspace,
capture_output=True,
text=True,
check=True,
)
except subprocess.CalledProcessError as e:
e.add_note(
"==================== STDOUT BEGIN ====================\n"
f"{e.stdout}"
"==================== STDOUT END ====================\n"
"==================== STDERR BEGIN ====================\n"
f"{e.stderr}"
"==================== STDERR END ===================="
)
raise
return result.stdout


def main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(
description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter,
)
mode = parser.add_mutually_exclusive_group()
mode.add_argument(
"--base",
default="upstream/main",
help="Git ref whose presubmit.yml to compare with (default: %(default)s).",
)
mode.add_argument(
"--flag",
help="List the tasks that pass this flag, e.g. --flag=--config=ci.",
)
args = parser.parse_args(argv)

workspace = Path(os.environ["BUILD_WORKSPACE_DIRECTORY"])
presubmit = workspace / presubmit_flags.PRESUBMIT_PATH
workspace_tasks = presubmit_flags.load_tasks(presubmit.read_text(encoding="utf-8"))

if args.flag:
lines = presubmit_flags.tasks_with_flag(workspace_tasks, args.flag)
print("\n".join(lines) if lines else f"No task passes {args.flag}.")
return 0

base_text = _git_show(workspace, f"{args.base}:{presubmit_flags.PRESUBMIT_PATH}")
base_tasks = presubmit_flags.load_tasks(base_text)
lines = presubmit_flags.diff_tasks(base_tasks, workspace_tasks)
print("\n".join(lines) if lines else f"No task's flags differ from {args.base}.")
return 0


if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
101 changes: 101 additions & 0 deletions dev/bazelci/presubmit_flags.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
"""Reads the build and test flags of BazelCI presubmit tasks.

BazelCI's bazelci.py loads `.bazelci/presubmit.yml` with `yaml.safe_load`, so
YAML merge keys (`<<:`) resolve the way PyYAML resolves them. It then flattens
each task's `build_flags` and `test_flags` with `flatten()`, which yields a
mapping's keys. This module mirrors that, except that it doesn't expand the
task matrix: matrix values only fill `${{ }}` placeholders, so a task stands
for all of its matrix jobs.

See https://github.com/bazelbuild/continuous-integration/blob/master/buildkite/bazelci.py
"""

from __future__ import annotations

from collections.abc import Iterable, Mapping

import yaml

PRESUBMIT_PATH = ".bazelci/presubmit.yml"
FLAG_ATTRS = (
# keep-sorted start
"build_flags",
"test_flags",
# keep-sorted end
)


def load_tasks(text: str) -> dict[str, dict[str, object]]:
"""Returns the tasks of a presubmit.yml, with YAML merges resolved."""
return yaml.safe_load(text)["tasks"]


def diff_tasks(
old_tasks: Mapping[str, Mapping[str, object]],
new_tasks: Mapping[str, Mapping[str, object]],
) -> list[str]:
"""Describes how each task's flags changed between two presubmit.yml files.

Args:
old_tasks: The tasks before the change, from `load_tasks`.
new_tasks: The tasks after the change, from `load_tasks`.

Returns:
One line per added task, removed task, or changed flags attribute,
sorted by task. A changed attribute lists removed flags with `-` and
added flags with `+`, then the new order if the kept flags changed
order, since Bazel uses a repeated flag's last value.
"""
lines = []
for name in sorted(old_tasks.keys() | new_tasks.keys()):
if name not in new_tasks:
lines.append(f"{name}: removed")
continue
if name not in old_tasks:
parts = []
for attr in FLAG_ATTRS:
flags = " ".join(_task_flags(new_tasks[name], attr)) or "(none)"
parts.append(f"{attr}: {flags}")
lines.append(f"{name}: added; {'; '.join(parts)}")
continue
for attr in FLAG_ATTRS:
old_flags = _task_flags(old_tasks[name], attr)
new_flags = _task_flags(new_tasks[name], attr)
if old_flags == new_flags:
continue
changes = [f"-{flag}" for flag in old_flags if flag not in new_flags]
changes += [f"+{flag}" for flag in new_flags if flag not in old_flags]
kept_old = [flag for flag in old_flags if flag in new_flags]
kept_new = [flag for flag in new_flags if flag in old_flags]
if kept_old != kept_new:
changes += ["reordered:", *new_flags]
lines.append(f"{name}: {attr}: {' '.join(changes)}")
return lines


def tasks_with_flag(tasks: Mapping[str, Mapping[str, object]], flag: str) -> list[str]:
"""Lists the tasks that pass `flag`, and in which flags attributes."""
lines = []
for name in sorted(tasks):
attrs = [attr for attr in FLAG_ATTRS if flag in _task_flags(tasks[name], attr)]
if attrs:
lines.append(f"{name}: {', '.join(attrs)}")
return lines


def _flatten(value: Iterable[object]) -> list[str]:
# Like bazelci.py's `flatten()`: keeps strings, expands one level of
# nested lists, and drops anything else.
flags = []
for item in value:
if isinstance(item, str):
flags.append(item)
elif isinstance(item, list):
flags.extend(item)
return flags


def _task_flags(task: Mapping[str, object], attr: str) -> list[str]:
value = task.get(attr, {})
assert isinstance(value, (dict, list)) # type assert
return _flatten(value)
11 changes: 11 additions & 0 deletions tests/bazelci/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
load("//python:pytest_test.bzl", "pytest_test")

pytest_test(
name = "presubmit_test",
srcs = ["presubmit_test.py"],
data = ["//.bazelci:presubmit_yml"],
deps = [
"//dev/bazelci:presubmit_flags",
"//python/runfiles",
],
)
32 changes: 32 additions & 0 deletions tests/bazelci/presubmit_test.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
"""Checks that .bazelci/presubmit.yml writes flags as mappings of `?` keys."""

from __future__ import annotations

from collections.abc import Mapping

from dev.bazelci import presubmit_flags
from python.runfiles import runfiles


def _find_problems(tasks: Mapping[str, Mapping[str, object]]) -> list[str]:
problems = []
for name, task in tasks.items():
for attr in presubmit_flags.FLAG_ATTRS:
value = task.get(attr, {})
if not isinstance(value, dict):
problems.append(f'{name}: {attr} isn\'t a mapping of `? "--flag"` keys')
elif any(v is not None for v in value.values()):
problems.append(f"{name}: {attr} has `?` keys with values")
return sorted(problems)


def test_presubmit_has_no_flag_problems():
rf = runfiles.CreateOrRaise()
presubmit = rf.root() / "rules_python" / presubmit_flags.PRESUBMIT_PATH
tasks = presubmit_flags.load_tasks(presubmit.read_text(encoding="utf-8"))

problems = _find_problems(tasks)

assert not problems, (
f"Fix these tasks in {presubmit_flags.PRESUBMIT_PATH}:\n" + "\n".join(problems)
)
Loading