diff --git a/.agents/rules/docs.md b/.agents/rules/docs.md index a0311901c6..987dacfc93 100644 --- a/.agents/rules/docs.md +++ b/.agents/rules/docs.md @@ -9,6 +9,12 @@ globs: docs/*.md * Act as an expert in tech writing, Sphinx, MyST, and markdown. * Wrap lines at 80 columns. * Use hyphens (`-`) in file names instead of underscores (`_`). +* **How-to Guides (`docs/howto/`)**: + * Prefer adding sections to an existing topical guide (e.g. + `docs/howto/build-a-wheel.md`) over creating a separate granular file. + * Write from the user's task perspective (e.g. "How do I generate the right + wheel filename for the active Python version?") rather than internal rule + or provider jargon, and omit low-level implementation parentheticals. * In Sphinx MyST markup, outer directives must have more colons than inner directives. * When adding `{versionadded}` or `{versionchanged}` sections, add them at the end of the documentation text. * For unreleased features or attributes, use `VERSION_NEXT_FEATURE` in diff --git a/.agents/rules/news.md b/.agents/rules/news.md index 760ca46c3f..cedb57424f 100644 --- a/.agents/rules/news.md +++ b/.agents/rules/news.md @@ -21,6 +21,8 @@ Before drafting any news entry, adhere strictly to the rules in ## Brevity and Content * Write a short snippet (1-2 concise sentences) so the combined `CHANGELOG.md` is easy to skim and grok. +* Summarize the capability rather than listing every new variable, attribute, or + field name (leave exhaustive lists to the API reference docs). * State high-level, user-visible behavior and outcomes (what now works, what changed). * Omit internal implementation details, refactoring mechanics, and exhaustive diff --git a/.agents/rules/starlark.md b/.agents/rules/starlark.md index f0f798074f..d9bf70633b 100644 --- a/.agents/rules/starlark.md +++ b/.agents/rules/starlark.md @@ -62,6 +62,12 @@ globs: "*.bzl,BUILD,BUILD.bazel,*.bazel" not use mutable `list[T]`. ## Code Style & Conventions +* **Direct Attribute Access**: Use normal attribute access (`x.field`) instead + of `getattr(x, "field", default)` for fields defined on a provider or struct + schema. When an object may be one of multiple provider/struct variants with + different field sets, guard once with `if hasattr(x, "field"):` (with a + comment explaining why the field may be absent) and use normal attribute + access inside the block. * **Dict union (`|`)**: Use `|` instead of `dicts.add(...)` from `@bazel_skylib//lib:dicts.bzl` when merging dictionaries. * **Type Checks (`@bazel_skylib//lib:types.bzl`)**: Prefer `types.is_*` helpers diff --git a/.agents/skills/review-code/review-news-prompt.md b/.agents/skills/review-code/review-news-prompt.md index d7c72d7fc6..6570bf285a 100644 --- a/.agents/skills/review-code/review-news-prompt.md +++ b/.agents/skills/review-code/review-news-prompt.md @@ -23,8 +23,9 @@ Your sole task is to audit `news/` fragment files and user-visible changes in - Verify each news entry is a short snippet (1-2 concise sentences) that is easy to skim and grok when combined into `CHANGELOG.md`. - Flag overly long, verbose entries or entries that explain internal - implementation details, background rationale, or exhaustive edge cases - (provide a shortened rewrite in your report). + implementation details, background rationale, exhaustive lists of symbol + names, or exhaustive edge cases (provide a shortened rewrite in your + report). 5. **Formatting & Cross-References**: - Verify no leading bullet points (`*` or `-`). - Verify subsystem prefix in parentheses when applicable (e.g., `(pypi)`,