(spark) branch branch-4.x updated: [MINOR][DOC] Suggest grouping code into sections when adding class members in AGENTS.md

[we...@apache.org]

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 <sz...@gmail.com>
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 <sz...@gmail.com>
    Signed-off-by: Wenchen Fan <we...@databricks.com>
    (cherry picked from commit e5a596325fc190749ae1e69895ab93ef4fe43b3c)
    Signed-off-by: Wenchen Fan <we...@databricks.com>
---
 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: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org