This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris.git
The following commit(s) were added to refs/heads/master by this push:
new b1720bdaee9 [chore](pr-template) Adopt a per-type PR template and use
it for commit messages (#70175)
b1720bdaee9 is described below
commit b1720bdaee9c26c2b68c6955837257dd901bd736
Author: Mingyu Chen (Rayner) <[email protected]>
AuthorDate: Wed Nov 4 10:30:03 2026 +0000
[chore](pr-template) Adopt a per-type PR template and use it for commit
messages (#70175)
### Background
Every PR against `master` starts from
`.github/PULL_REQUEST_TEMPLATE.md`, and the root `AGENTS.md` tells
coding agents to write commit messages in the same layout. The current
template asks for a problem summary, a release note, and checkboxes for
tests, behavior changes, and documentation. Doris merges PRs by
squashing, so the description becomes the commit message on `master`.
### What problem does this PR solve?
Issue Number: None
Related PR: #42999 (introduced the current template), #70123 (a
description written in this layout)
PR Type: Build/CI/Chore
Problem Summary:
The current template leaves out what reviewers most often have to ask
for: the context of the module, why the change is needed and why this
approach, why existing tests missed a bug, and what was verified. Many
PRs leave its checkboxes unticked. This PR replaces it with a layout
that opens with Background, has required fields for each PR type, asks a
diff of more than about 300 changed lines to open Details with a Change
map, and adds Testing, optional Notes for Reviewers, a pre-submission
status, and an AI disclosure. Commit messages written by `AGENTS.md`
rules follow the same layout.
### Details
- **Affected:** `.github/PULL_REQUEST_TEMPLATE.md`, which every new PR
description starts from, and the commit and worktree rules in the root
`AGENTS.md`. No build scripts, CI jobs, or workflows change;
`title-checker.yml` accepts the same `[type](scope)` titles as before.
- **Developer and release impact:** Authors fill in more sections, with
the required fields of each PR type listed in a comment under Details;
the reviewer checklist is gone. Coding agents write commit messages in
the new layout, and from a worktree they may keep PR handoff files in
`${DORIS_REPO}/.git/pr-handoff/`. Releases are unaffected.
- **License and third-party:** None.
- **Rollback:** Revert this PR; nothing else depends on the template.
### Testing
- `check_pr.py`, the checker of the `doris-pr-description` skill (not
part of this PR; see Notes for Reviewers), reports the unfilled template
as not ready, with 17 errors that include the empty Background, Problem
Summary, Testing, and Release note and every blank answer line. Its
eleven bundled examples, one or two per PR type and written in this
layout, pass it, and so does this description.
- The description of #70123, written in this layout, passes the same
checker, with one warning that its prose is longer than the limit.
### Notes for Reviewers
- Two commits: the template and the `AGENTS.md` rules, then guidance for
the Change map and three refined comments. With the HTML comments
removed, the second commit changes nothing.
- `AGENTS.md` also drops the second copy of the paragraph on which files
a commit may contain.
- The new `AGENTS.md` text names the `develop-with-evidence` and
`doris-pr-description` skills, which are not in this repository yet.
They are to be added to
[apache/doris-skills](https://github.com/apache/doris-skills), which a
later PR includes here as a git submodule.
### Release note
None
### Check List (For Author)
- Behavior changed: No
- Does this need documentation: No
- Pre-submission status: Ready
### AI Disclosure
- Tool: Claude Code (Claude Opus 5.5)
- Generated: the template, the `AGENTS.md` text, the commit messages,
and this description
- Human review: The author reviewed all of the changes line by line.
---
.github/PULL_REQUEST_TEMPLATE.md | 73 +++++++++++++++++++++++++++-------------
AGENTS.md | 42 +++++------------------
2 files changed, 59 insertions(+), 56 deletions(-)
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index c7c41345761..204f435726c 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,39 +1,66 @@
+### Background
+
+<!-- How the feature or module this PR touches works today, in two to four
plain sentences, for a reviewer who doesn't know it. Link the user doc if there
is one. Leave the problem and the fix to Problem Summary. -->
+
### What problem does this PR solve?
-Issue Number: close #xxx
+<!-- Issue Number: "close #N" if this PR resolves the issue, "#N" if it only
relates to it, "None" if there is none. A Feature needs an issue. -->
+<!-- Related PR: "#N (relation)" for each PR a reviewer should know about,
such as "#123 (introduced the bug)", separated by commas. Write "None" if no
related PR is known. -->
+<!-- PR Type: Bugfix, Performance, Feature, Enhancement, Refactor, Test,
Build/CI/Chore, Revert, Release/Dependency, or Other. -->
-Related PR: #xxx
+Issue Number:
+Related PR:
+PR Type:
Problem Summary:
+<!-- Two to five sentences: the problem or need and who is affected; the
approach in one sentence; when the diff is larger than that suggests, what else
it had to handle, or that most of it is tests; and what existing users see
after an upgrade. -->
+
+### Details
+
+<!--
+For a diff of more than about 300 changed lines, start with "- **Change
map:**": how many lines are production code, tests, generated files, and docs,
then the code in parts, each with the problem it handles and its size.
+Then answer each field of your PR type on its own line, as "- **Field:**
answer", in this order:
+ Bugfix: Frequency, Root cause, Why existing tests missed it, Fix, Other
paths and branches
+ Performance: Why it was slow, Optimization, Results, Applicability and cost
+ Feature: Scope, Design, Usage, Default behavior, Compatibility
+ Enhancement: Before and after, Configs and defaults, Impact on existing users
+ Refactor: Moves vs. logic changes, Behavior change, Compatibility,
Performance impact, Rollback
+ Test, adding tests: Scenarios, What existing tests miss, Fails when broken
+ Test, fixing a test: Failure, Cause, Stability evidence
+ Build/CI/Chore: Affected, Developer and release impact, License and
third-party, Rollback
+ Revert: Why not fix forward, Original author notified, Follow-up
+ Release/Dependency: Versions, Upstream changes, Compatibility, Rollback
+ Other: Why Other
+"None" is a valid answer when it is true. Don't restate the diff.
+-->
+
+### Testing
+
+<!-- The tests, suites, or commands that ran, what each shows, and where it
ran (locally or in CI). For a fix, the test that fails before it and passes
after. -->
+
+### Notes for Reviewers
+
+<!-- Optional; delete this section if there is nothing to say. Why each
non-obvious edit was made, what you are unsure about, and where to start
reading if Details has no Change map. -->
+
### Release note
-None
+<!-- One paragraph on what users will notice, or None. -->
### Check List (For Author)
-- Test <!-- At least one of them must be included. -->
- - [ ] Regression test
- - [ ] Unit Test
- - [ ] Manual test (add detailed scripts or steps below)
- - [ ] No need to test or manual test. Explain why:
- - [ ] This is a refactor/code format and no logic has been changed.
- - [ ] Previous test can cover this change.
- - [ ] No code files have been changed.
- - [ ] Other reason <!-- Add your reason? -->
+<!-- Behavior changed: "No", or "Yes (see Details)" with a Behavior change
field in Details. -->
+<!-- Does this need documentation: "No", or "Yes" with the
apache/doris-website PR or the plan. -->
+<!-- Pre-submission status: "Ready"; "Partially verified: " and what is not
verified; or "Not ready: " and why, for a Draft PR. -->
- Behavior changed:
- - [ ] No.
- - [ ] Yes. <!-- Explain the behavior change -->
-
-- Does this need documentation?
- - [ ] No.
- - [ ] Yes. <!-- Add document PR link here. eg:
https://github.com/apache/doris-website/pull/1214 -->
+- Does this need documentation:
+- Pre-submission status:
-### Check List (For Reviewer who merge this PR)
+### AI Disclosure
-- [ ] Confirm the release note
-- [ ] Confirm test cases
-- [ ] Confirm document
-- [ ] Add branch pick label <!-- Add branch pick label that this PR should
merge into -->
+<!-- Tool: the agent and model, or None. Generated: the parts it wrote (code,
tests, this description), or None. Human review: what you reviewed of the
generated parts, or "Not applicable" without AI tools. You may add "- Prompts:"
to summarize how you directed the agent. -->
+- Tool:
+- Generated:
+- Human review:
diff --git a/AGENTS.md b/AGENTS.md
index c87e65dbb30..b16c7f794e2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,7 +28,7 @@ To ensure smooth test execution without interference between
worktrees, the firs
Submodules are not part of the default worktree setup. If the task does not
compile Doris or run tests that require submodules, leave all submodules
uninitialized. Build and test entry points initialize the submodule paths they
require. Only initialize a submodule manually when the task actually needs it
and an entry point does not handle it; initialize the exact required path
instead of running an unscoped recursive update for every submodule.
-When working in worktree mode, all operations must be confined to the current
worktree directory. Do not enter `${DORIS_REPO}` or use any resources there.
Compilation and execution must be done within the current worktree directory.
The compiled Doris cluster must use random ports not used by other worktrees
(modify BE and FE conf before compilation, using a uniform offset of
`${DORIS_PORT_OFFSET_RANGE}` from default ports without conflicting with other
worktrees' ports). Run from the `o [...]
+When working in worktree mode, all operations must be confined to the current
worktree directory. Do not enter `${DORIS_REPO}` or use any resources there.
Git's own storage in `${DORIS_REPO}/.git`, which every worktree shares, is not
such a resource. This includes the PR handoff files in
`${DORIS_REPO}/.git/pr-handoff/`, which a development skill such as
`develop-with-evidence` writes and the `doris-pr-description` skill reads.
Compilation and execution must be done within the current wo [...]
## Coding Standards
@@ -85,38 +85,14 @@ Added regression tests must comply with the following
standards:
Files in git commit should only be related to the current modification task.
Environment modifications for running (e.g., `conf/`, `AGENTS.md`, `hooks/`,
etc.) must not be `git add`ed. When delivering the final task, you must ensure
all actual code modifications have been committed.
-Commit messages must follow the format below, which mirrors the PR template
(`.github/PULL_REQUEST_TEMPLATE.md`):
-
-```
-[<type>](<module>) <Short summary of the change>
-
-### What problem does this PR solve?
-
-Issue Number: close #xxx
-
-Related PR: #xxx
-
-Problem Summary: <Describe the problem this commit addresses>
-
-### Release note
-
-<If applicable, describe user-visible changes; otherwise write "None">
-
-### Check List (For Author)
-
-- Test: <Specify which testing was done>
- - Regression test / Unit Test / Manual test / No need to test (with reason)
-- Behavior changed: No / Yes (with explanation)
-- Does this need documentation: No / Yes (with doc PR link)
-```
+Commit messages follow the PR template, `.github/PULL_REQUEST_TEMPLATE.md`:
the title on the first line, a blank line, and then the template's sections,
filled in, with the guidance comments deleted. The `doris-pr-description` skill
explains each section and field.
Key rules for commit messages:
-1. The title must follow the `[type](module)` format validated by the PR title
checker (`.github/workflows/title-checker.yml`). Common types include: `fix`,
`feature`, `improvement`, `refactor`, `chore`, `test`, `doc`. Common modules
include: `fe`, `be`, `cloud`, `regression`, `build`
-2. The short summary must be concise and written in imperative mood (e.g.,
`[fix](fe) Fix null pointer in scan node` not `[fix](fe) Fixed null pointer`)
-3. The `Issue Number` field must reference the corresponding GitHub Issue with
`close #xxx` syntax when applicable
-4. The `Release note` section must be filled in for any user-visible behavior
or feature change; write "None" for internal refactoring or test-only changes
-5. The `Problem Summary` section should cover the following content when
available: problem reproduction method, root cause in code, end-to-end
results/phenomena before and after repair, and the fix. If it's a refactoring,
explain the reason. If it's a performance improvement, specify the case and the
exact improvement amount. DO NOT mention any specific JIRA numbers. The
background of the problem should be fully understandable through this section
alone.
-6. The test section must honestly reflect the testing performed; do not claim
tests that were not actually run
-
-Files in a git commit should only be related to the current modification task.
Environment modifications for running (for example `conf/`, `AGENTS.md`,
`hooks/`) must not be `git add`ed. When delivering the final task, ensure all
actual code modifications have been committed.
+1. The title is `[<tag>](<scope>) <Summary>`, which the PR title checker
(`.github/workflows/title-checker.yml`) validates. The tag follows the PR type:
`fix` (Bugfix), `opt` (Performance), `feature` (Feature), `improvement`
(Enhancement), `refactor` (Refactor), `test` (Test), `chore` (Build/CI/Chore,
including documentation in this repository), `deps` (Release/Dependency), and
`other` (Other). A revert keeps GitHub's `Revert "<original title>"`. The scope
is lowercase and names the area [...]
+2. The summary is concise and in imperative mood (e.g., `[fix](fe) Fix null
pointer in scan node`, not `[fix](fe) Fixed null pointer`).
+3. `Issue Number` is `close #N` when the change resolves the issue, `#N` when
it only relates to it, and `None` otherwise. A Feature needs an issue; when its
issue will be opened together with the PR, write `Issue Number: TODO(author):
the issue is opened with the PR` until then.
+4. The `Details` section answers the required fields of the PR type, such as
the root cause and why existing tests missed the bug for a Bugfix, or the
numbers for a Performance change.
+5. The `Release note` section describes what users will notice; write `None`
for refactors, tests, and other changes users don't see.
+6. The `Testing` section and the pre-submission status must honestly reflect
the testing performed; do not claim tests that were not actually run.
+7. Do not mention JIRA numbers or other internal tracker IDs, private links,
or customer names.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
