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]