This is an automated email from the ASF dual-hosted git repository.
cloud-fan pushed a commit to branch branch-4.x
in repository https://gitbox.apache.org/repos/asf/spark.git
The following commit(s) were added to refs/heads/branch-4.x by this push:
new d01fa3fe8349 [MINOR][DOC] Suggest grouping code into sections when
adding class members in AGENTS.md
d01fa3fe8349 is described below
commit d01fa3fe8349466df0d0ffc66d2459d330f6c6ed
Author: Szehon Ho <[email protected]>
AuthorDate: Tue Aug 11 15:54:01 2026 +0800
[MINOR][DOC] Suggest grouping code into sections when adding class members
in AGENTS.md
### What changes were proposed in this pull request?
Adds one paragraph to the `## Development Notes` section of `AGENTS.md` on
where to place new members when editing an existing class or object: keep
related kinds of code in sections and append a new member to the matching
section, rather than inserting it into the middle of another section. It
sketches a common layout (fields and constructors, then the public/override
API, then private helpers; in a test suite, tests together with helpers after
them) and names the failure mode it is [...]
It is phrased as a suggestion with a default, not a rule. Files in the repo
vary in how they order members, so the note defers to the file's existing
sectioning and explicitly does not ask anyone to reorganize existing code.
### Why are the changes needed?
Agents writing code top-down tend to define a member immediately above its
first use, which lands it in the middle of a class's public surface or a
suite's list of test cases and interrupts a top-to-bottom read. I hit exactly
this while writing a test suite and had to move the code in review.
This fits the existing pattern of the surrounding notes, which call out
specific, recurring failure modes (non-ASCII characters in comments,
overrunning the 100-character line limit) rather than restating general style
guidance. Unlike those two, this one has no linter behind it, so the note is
the only signal available.
### Does this PR introduce _any_ user-facing change?
No. Documentation for contributors and agent tooling only.
### How was this patch tested?
No tests; documentation only. Verified the added text is pure ASCII, per
the rule in the paragraph immediately below it:
```
git diff -U0 -- AGENTS.md | grep '^+' | grep -v '^+++' | grep -P
"[^\x00-\x7F]"
```
### Was this patch authored or co-authored using generative AI tooling?
Generated-by: Cursor (Opus 5)
Closes #57803 from szehon-ho/agents-member-placement.
Authored-by: Szehon Ho <[email protected]>
Signed-off-by: Wenchen Fan <[email protected]>
(cherry picked from commit e5a596325fc190749ae1e69895ab93ef4fe43b3c)
Signed-off-by: Wenchen Fan <[email protected]>
---
AGENTS.md | 2 ++
1 file changed, 2 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
index 11bc4ad9484d..1d2fc98b6c7e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,6 +18,8 @@ SQL golden file tests are managed by `SQLQueryTestSuite` and
its variants. Read
Spark Connect protocol is defined in proto files under
`sql/connect/common/src/main/protobuf/`. Read the README there before modifying
proto definitions.
+When adding a member to an existing class or object, follow the sectioning the
file already uses and put the new member with the code it belongs with. The
common failure mode is dropping it wherever it is first used without checking
how the file is organized, splitting a section of unrelated code in the
process. Beyond grouping related code there is no prescribed order -- the
Databricks Scala guide, which Spark follows, asks only that a long class group
its members into logical sections [...]
+
Avoid introducing non-ASCII characters in code or comments. String literals
may contain non-ASCII when the content requires it (error messages, test data,
etc.). Identifiers are ASCII by convention. The common failure mode is
typographic characters (em-dash, smart quotes, ellipsis, non-breaking space)
sneaking into comments; scalastyle flags some of these. Spot-check before
committing: `grep -rn -P "[^\x00-\x7F]" <files>`.
Keep source lines within 100 characters — the linters enforce this for Scala,
Java, and Python, and LLMs commonly overrun it in comments and long
expressions. A quick scan of just the changed files catches most cases in
seconds, far cheaper than a CI round trip:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
