From 604c998df5251f0b9d1810e95ef7b6b2215e1a9b Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Wed, 2 Sep 2026 00:53:18 -0700 Subject: [PATCH] agents: update news and PR conventions Add explicit constraints to .agents/rules/news.md to focus on user-visible outcomes and restrict {obj} cross-references to documented API symbols. Update .agents/rules/pr.md to preserve existing author descriptions and wrap at 72 columns. --- .agents/rules/news.md | 10 +++++++--- .agents/rules/pr.md | 2 ++ 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/.agents/rules/news.md b/.agents/rules/news.md index 7946967ad4..71e63f94ff 100644 --- a/.agents/rules/news.md +++ b/.agents/rules/news.md @@ -12,9 +12,13 @@ Before drafting any news entry, adhere strictly to the rules in `CONTRIBUTING.md` above. ## Sphinx MyST Cross-Reference Syntax (`{obj}`) -* Use `{obj}\`\`` in news entries for rules, macros, targets, providers, - attributes, args, and any other cross-referencable Starlark or Python - objects. +* Use `{obj}\`\`` only for cross-referencable Starlark or Python API + symbols (rules, macros, targets, providers, attributes, args). +* Never use `{obj}` on metadata files (e.g. `RECORD`), file paths, or tools. + +## Content +* State user-visible behavior and outcomes (what now works, what changed). +* Omit internal implementation and refactoring details. ## GitHub Issue Link Formatting * Append GitHub issue cross-references at the end of news entries in markdown diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md index 20690eb6ab..7c49497a0c 100644 --- a/.agents/rules/pr.md +++ b/.agents/rules/pr.md @@ -43,3 +43,5 @@ Before drafting any pull request description, strictly adhere to the rules in conceptual level. Link related issues (e.g. `Work towards #`). * **Conciseness & Style (Strunk & White)**: Omit needless words. Use clear, active, and direct phrasing for *why* and *how*. +* **Preserve Existing Descriptions**: Preserve the author's wording unless + instructed to change it. Wrap bodies at 72 columns.