This is an automated email from the ASF dual-hosted git repository.

morningman pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/doris-skills.git


The following commit(s) were added to refs/heads/main by this push:
     new c353d71  feat(doris-pr-description): show the problem with a concrete 
example (#17)
c353d71 is described below

commit c353d71bc50d6c0baf1831dec33cbfa0abc64ef2
Author: Mingyu Chen (Rayner) <[email protected]>
AuthorDate: Sat Nov 14 10:33:09 2026 +0800

    feat(doris-pr-description): show the problem with a concrete example (#17)
    
    Reviewers who don't know the module get the point of a PR from one real
    case faster than from a paragraph about it. Problem Summary now ends
    with one simple, concrete example whenever the problem fits in a few
    lines: the smallest statement that triggers it and what it gives before
    and after the change, with SQL in a fenced block and the comparison in
    a table. Every output is copied from a run; an example that needs more
    than a few lines goes in the issue, and Problem Summary points to it.
    
    The rule is in write.md, with the matching parts of issue.md (Current
    and Expected behavior), development.md (development records the example
    while the code without the change is at hand; develop-with-evidence
    reads only this file and the type file), the Bugfix type (Problem
    Summary and Frequency), the Enhancement type (Before and after does not
    repeat the example), and the Bugfix example.
    
    check_pr.py no longer counts a table in Problem Summary toward its
    150-word warning, as it already left out code blocks; otherwise an
    example table sets the warning off.
    
    Co-authored-by: morningman <[email protected]>
    Co-authored-by: Claude Opus 5.5 <[email protected]>
---
 skills/doris-pr-description/references/development.md       |  2 +-
 skills/doris-pr-description/references/examples/bugfix.md   | 11 +++++++++++
 skills/doris-pr-description/references/issue.md             |  4 ++--
 skills/doris-pr-description/references/types/bugfix.md      |  4 ++--
 skills/doris-pr-description/references/types/enhancement.md |  2 +-
 skills/doris-pr-description/references/write.md             |  2 ++
 skills/doris-pr-description/scripts/check_pr.py             |  4 +++-
 7 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/skills/doris-pr-description/references/development.md 
b/skills/doris-pr-description/references/development.md
index d4c61f9..b8f2dd2 100644
--- a/skills/doris-pr-description/references/development.md
+++ b/skills/doris-pr-description/references/development.md
@@ -9,7 +9,7 @@ A development skill such as `develop-with-evidence` reads this 
file at the start
    - for a Bugfix, the PR that introduced the bug and the release branches 
that have it: `references/facts/bugfix-origin.md`;
    - when the change moves a submodule pointer, the range it moves and whether 
the new pin is on the branch: `references/facts/submodules.md`.
 4. Record the results in English in the handoff file:
-   - in its description draft: the PR type, the title, Background, the problem 
and the approach for Problem Summary, `Issue Number`, `Related PR`, the type's 
fields, Testing, Release note, and the Check List with the documentation plan. 
`Related PR` holds the PRs known from the work, such as the one that introduced 
a bug or the ones the change builds on or depends on, or `None`; don't search 
GitHub for other PRs on the same problem;
+   - in its description draft: the PR type, the title, Background, the problem 
and the approach for Problem Summary, `Issue Number`, `Related PR`, the type's 
fields, Testing, Release note, and the Check List with the documentation plan. 
When the problem can be shown in a few lines, Problem Summary shows it with one 
simple, concrete example: the smallest input, such as a single SQL statement, 
and what it gives before and after the change, copied from the runs; the code 
without the change  [...]
    - beside the draft: the decisions and their alternatives, the parts of the 
change, the reasons for non-obvious edits, the existing tests, the evidence, 
the pre-submission status, and how AI was used.
 
 Left to the PR step: the line counts of the final diff, the review threads of 
an open PR, the author's statement on how much of the AI-generated work they 
reviewed, the issue a Feature without one needs, and the final wording of the 
description.
diff --git a/skills/doris-pr-description/references/examples/bugfix.md 
b/skills/doris-pr-description/references/examples/bugfix.md
index 443b618..a78015e 100644
--- a/skills/doris-pr-description/references/examples/bugfix.md
+++ b/skills/doris-pr-description/references/examples/bugfix.md
@@ -19,6 +19,17 @@ Problem Summary:
 
 After an Iceberg table's partition spec replaces `identity(dt)` with 
`day(ts)`, Doris returns NULL for `dt` in rows from files written under the old 
spec, while Spark returns the right values. This PR reads each file's partition 
values with the spec that the file was written with.
 
+For example, when the rows of `2026-01-05` were written before the spec 
changed and those of `2026-01-06` after it:
+
+```sql
+SELECT dt, count(*) FROM iceberg_catalog.db.events GROUP BY dt ORDER BY dt;
+```
+
+| Before the fix | With the fix |
+|---|---|
+| `NULL, 3` | `2026-01-05, 3` |
+| `2026-01-06, 5` | `2026-01-06, 5` |
+
 ### Details
 
 - **Frequency:** Always, on Iceberg tables whose partition spec has replaced a 
field and that still hold files written under the old spec.
diff --git a/skills/doris-pr-description/references/issue.md 
b/skills/doris-pr-description/references/issue.md
index fd76fe2..b1cf274 100644
--- a/skills/doris-pr-description/references/issue.md
+++ b/skills/doris-pr-description/references/issue.md
@@ -26,11 +26,11 @@ Why this issue exists: the user scenario, the need, or the 
incident.
 
 ### Current behavior
 
-What happens today. For a bug, include the Doris version and the deployment 
mode.
+What happens today, shown with a simple, concrete example whenever it can be: 
the statement, and the result, error, or log line it gives, copied from a run. 
For a bug, include the Doris version and the deployment mode.
 
 ### Expected behavior
 
-What should happen instead.
+What should happen instead, on the same example.
 
 ### Proposed design
 
diff --git a/skills/doris-pr-description/references/types/bugfix.md 
b/skills/doris-pr-description/references/types/bugfix.md
index 5f43945..46c5781 100644
--- a/skills/doris-pr-description/references/types/bugfix.md
+++ b/skills/doris-pr-description/references/types/bugfix.md
@@ -14,11 +14,11 @@ How the affected feature works when it works: the mechanism 
the bug sits in, and
 
 ## Problem Summary
 
-The symptom as a user or developer sees it (the wrong result, the error text, 
where it crashes), who runs into it, and the fix in one sentence.
+The symptom as a user or developer sees it (the wrong result, the error text, 
where it crashes), who runs into it, and the fix in one sentence. Then the 
shortest reproduction, as the example that `references/write.md` describes: the 
statement, and what it gives before and after the fix.
 
 ## Details
 
-- **Frequency** (required): `Always`, `Intermittent`, or `Not observed`, 
followed by the trigger: the conditions, or the shortest reproduction. For an 
intermittent bug, give the rate if it is known (`about 1 in 20 P0 runs`). For a 
bug found by reading code, say so: `Not observed; found by code review. 
Triggers when ...`. When the trigger depends on an external system, describe 
the behavior that triggers it (`REST catalogs that answer a table lookup for a 
view with HTTP 400`) and name the [...]
+- **Frequency** (required): `Always`, `Intermittent`, or `Not observed`, 
followed by the trigger: the conditions, or the shortest reproduction, which 
can refer to the example in Problem Summary instead of repeating it. For an 
intermittent bug, give the rate if it is known (`about 1 in 20 P0 runs`). For a 
bug found by reading code, say so: `Not observed; found by code review. 
Triggers when ...`. When the trigger depends on an external system, describe 
the behavior that triggers it (`REST  [...]
 - **Root cause** (required): which code is wrong, and why it produces the 
symptom. Name the function or class, in one to three sentences.
 - **Why existing tests missed it** (required): cover both layers, the unit 
tests and the end-to-end regression suites under `regression-test/suites/`. For 
each layer, name the closest tests, say what they check, and give the gap that 
let the bug through; if no test at a layer reaches the faulty code, say so. 
`references/facts/existing-tests.md` shows how to find the tests and check that 
CI runs them. Common gaps:
   - No case for the trigger condition.
diff --git a/skills/doris-pr-description/references/types/enhancement.md 
b/skills/doris-pr-description/references/types/enhancement.md
index f9759a1..38f6afd 100644
--- a/skills/doris-pr-description/references/types/enhancement.md
+++ b/skills/doris-pr-description/references/types/enhancement.md
@@ -19,7 +19,7 @@ What is inconvenient or limited today, who runs into it, and 
what the PR changes
 
 ## Details
 
-- **Before and after** (required): the exact behavior before and after: the 
output, the error text, the limits, the defaults. Show a short example when 
words alone are ambiguous.
+- **Before and after** (required): the exact behavior before and after: the 
output, the error text, the limits, the defaults. Show a short example when 
words alone are ambiguous, unless Problem Summary already shows it.
 - **Configs and defaults** (required): new or changed configs and session 
variables, with their defaults and whether they can change at runtime; or 
`None`.
 - **Impact on existing users** (required): what existing SQL, data, metadata, 
privileges, and clients will see, including after a running cluster is 
upgraded. When a default changes, give the value an upgraded cluster ends up 
with, and whether values persisted earlier (`SET GLOBAL`, `fe.conf`, table 
properties) override it.
 - **Results** (when the change also improves performance): as in Performance.
diff --git a/skills/doris-pr-description/references/write.md 
b/skills/doris-pr-description/references/write.md
index ac8ba41..72f6dfe 100644
--- a/skills/doris-pr-description/references/write.md
+++ b/skills/doris-pr-description/references/write.md
@@ -86,6 +86,8 @@ Problem Summary:
   3. When the diff is larger than sentence 2 suggests, why: what else the 
change had to handle, or that most of it is tests. Reviewers hold the summary 
against the size that GitHub shows, and a one-line switch next to 600 lines of 
code makes them suspect unrelated changes until they read the reason: `locking 
enable_audit_plugin alone is not enough: twelve other parameters can also skip 
statements, lose events, or cut the recorded text, so while the switch is on 
none of them can be set we [...]
   4. What existing users see after an upgrade if they change nothing, unless 
the type already makes it plain, as a bug fix does: `off by default, and with 
it off nothing changes`, or the exceptions.
 
+  Then, whenever the problem can be shown in a few lines, show it with one 
simple, concrete example: a reviewer who doesn't know the module gets the point 
from a real case faster than from any description of it. Take the smallest case 
that shows it, with what it gives before and after the change: for a bug, the 
shortest statement that triggers it and its wrong result, error, or log line; 
for a new or changed behavior, the statement or setting as users will write it; 
for a slowdown, the q [...]
+
   A side change, such as a small fix found on the way, gets a clause at most; 
its own field says the rest. Details go in fields.
 - **Details** holds the type's fields as `- **Field:** answer`, in the order 
of the type file, after the Change map when there is one. Required fields 
always appear; conditional fields appear only when they apply. Most answers are 
one to three sentences. `None` is a valid answer when it is true; padding is 
not.
 - **Change map** opens Details, in any type, when the diff has more than about 
300 changed lines. It tells reviewers where the lines go, so that they can size 
the review and see that nothing in it is unrelated. Take the numbers from 
`scripts/diff_profile.py` (step 1) rather than counting:
diff --git a/skills/doris-pr-description/scripts/check_pr.py 
b/skills/doris-pr-description/scripts/check_pr.py
index b28fcd1..8216a52 100755
--- a/skills/doris-pr-description/scripts/check_pr.py
+++ b/skills/doris-pr-description/scripts/check_pr.py
@@ -523,7 +523,9 @@ def check_body(rep, body, title_type, 
commented=frozenset(), changed_lines=None)
         if summary_lines is None:
             rep.error("Problem Summary", "label missing")
         else:
-            summary = text_of([(t, f) for t, f in summary_lines if not f])
+            # An example's code block or table doesn't count toward the 
summary's length.
+            summary = text_of([(t, f) for t, f in summary_lines
+                               if not f and not t.lstrip().startswith("|")])
             if is_empty(summary):
                 rep.error("Problem Summary", "empty")
             elif word_count(summary) > 150:


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to