This is an automated email from the ASF dual-hosted git repository.
ruanwenjun pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/dolphinscheduler.git
The following commit(s) were added to refs/heads/dev by this push:
new ac9741bf03 [Chore][Docs] Refresh commit message convention to match
current practice (#18242)
ac9741bf03 is described below
commit ac9741bf03bc7f61356f689c00434dfe42aadb36
Author: Wenjun Ruan <[email protected]>
AuthorDate: Mon May 11 09:07:19 2026 +0800
[Chore][Docs] Refresh commit message convention to match current practice
(#18242)
---
.gitignore | 1 +
CLAUDE.md | 4 +-
docs/docs/en/contribute/join/commit-message.md | 117 ++++++++++++-------------
docs/docs/en/contribute/join/pull-request.md | 7 +-
docs/docs/en/contribute/join/submit-code.md | 4 +-
docs/docs/zh/contribute/join/commit-message.md | 117 ++++++++++++-------------
docs/docs/zh/contribute/join/pull-request.md | 5 +-
docs/docs/zh/contribute/join/submit-code.md | 4 +-
8 files changed, 133 insertions(+), 126 deletions(-)
diff --git a/.gitignore b/.gitignore
index 482e117f35..ff6e43c416 100644
--- a/.gitignore
+++ b/.gitignore
@@ -59,3 +59,4 @@ ds_schema_check_test
# Agent
docs/superpowers/
.claude/worktrees
+CLAUDE.local.md
diff --git a/CLAUDE.md b/CLAUDE.md
index d5e10261b6..652184ba0d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -146,8 +146,8 @@ A **user** hits the UI, which calls the API server. The API
server writes to the
## Project-wide conventions
-- **Formatting**: `./mvnw spotless:apply`. CI will fail PRs that aren't
formatted. Java imports are ordered; license headers are enforced.
-- **Commit style**: `[Type-ISSUE_ID] [Scope] Subject`, e.g. `[Fix-18168]
[Worker] ...`. Scopes match module names.
+- **Formatting**: Run `./mvnw spotless:apply` before every commit/push.
Spotless covers Java sources, `pom.xml`, and Markdown files (yes, including the
docs); CI runs `./mvnw spotless:check` and will fail PRs that aren't formatted.
Java imports are ordered; license headers are enforced.
+- **Commit style**: `[Type-ISSUE_ID][Scope] Subject`, e.g.
`[Fix-18168][Worker] ...`. All types except `Chore` require an issue ID. See
[commit-message.md](docs/docs/en/contribute/join/commit-message.md) for the
full convention.
- **Branching**: `dev` is the main integration branch (not `main`/`master`).
- **PRs must link a GitHub issue** and keep their scope tight — one module /
one concern.
- **Do not break wire / DB compatibility** silently. Changes to `extract-*`
RPC interfaces, `dao` entities, enum values, and `spi.DbType` ripple to
deployed clusters mid-upgrade.
diff --git a/docs/docs/en/contribute/join/commit-message.md
b/docs/docs/en/contribute/join/commit-message.md
index 0e224aa987..3884913e8d 100644
--- a/docs/docs/en/contribute/join/commit-message.md
+++ b/docs/docs/en/contribute/join/commit-message.md
@@ -1,94 +1,91 @@
# Commit Message Notice
-### Preface
+A good commit message states **what changed and why** at a glance. The full
story belongs in the linked Issue / Pull Request — keep the commit message
itself concise.
-A good commit message can help other developers (or future developers) quickly
understand the context of related changes, and can also help project managers
determine whether the commit is suitable for inclusion in the release. But when
we checked the commit logs of many open source projects, we found an
interesting problem. Some developers have very good code quality, but the
commit message record is rather confusing. When other contributors or learners
are viewing the code, it can’t be [...]
-The purpose of the changes before and after the submission, as Peter Hutterer
said：Re-establishing the context of a piece of code is wasteful. We can’t avoid
it completely, so our efforts should go to reducing it as much as possible.
Commit messages can do exactly that and as a result, a commit message shows
whether a developer is a good collaborator. Therefore, DolphinScheduler
developed the protocol in conjunction with other communities and official
Apache documents.
+## Format
-### Commit Message RIP
-
-#### 1：Clearly modify the content
-
-A commit message should clearly state what issues (bug fixes, function
enhancements, etc.) the submission solves, so that other developers can better
track the issues and clarify the optimization during the version iteration
process.
-
-#### 2：Associate the corresponding Pull Request or Issue
-
-When our changes are large, the commit message should best be associated with
the relevant Issue or Pull Request on GitHub, so that our developers can
quickly understand the context of the code submission through the associated
information when reviewing the code. If the current commit is for an issue,
then the issue can be closed in the Footer section.
-
-#### 3：Unified format
-
-The formatted CommitMessage can help provide more historical information for
quick browsing, and it can also generate a Change Log directly from commit.
-
-Commit message should include three parts: Header, Body and Footer. Among
them, Header is required, Body and Footer can be omitted.
-
-##### Header
-
-The header part has only one line, including three fields: type (required),
scope (optional), and subject (required).
+```
+[Type-ISSUE_ID][Scope] Subject
-[DS-ISSUE number][type] subject
+(optional body — bullet list of the main changes)
-(1) Type is used to indicate the category of commit, and only the following 7
types are allowed.
+(optional footer — BREAKING CHANGE / Closes #xxx)
+```
-- feat：features
-- fix：Bug fixes
-- docs：Documentation
-- style： Format (does not affect changes in code operation)
-- refactor：Refactoring (It is not a new feature or a code change to fix a bug)
-- test：Add test
-- chore：Changes in the build process or auxiliary tools
+Header is required; body and footer are optional. Aim for a Subject under 72
characters so it does not get truncated on GitHub.
-If the type is feat and fix, the commit will definitely appear in the change
log. Other types (docs, chore, style, refactor, test) are not recommended.
+### Type (required)
-(2) Scope
+| Type | When to use
| Issue ID required? |
+|---------------|-----------------------------------------------------------------------------------------------------------|----------------------|
+| `Feature` | A new user-visible feature
| Yes |
+| `Improvement` | Enhancement to an existing feature (refactor, perf, UX
polish) | Yes |
+| `Fix` | Bug fix
| Yes |
+| `Doc` | Documentation only
| Yes |
+| `DSIP` | A change implementing a
[DSIP](https://github.com/apache/dolphinscheduler/issues?q=label%3ADSIP)
proposal | Yes (the DSIP issue) |
+| `Chore` | Build, CI, test scaffolding, dependency bumps, trivial
cleanup | No |
-Scope is used to indicate the scope of commit impact, such as server, remote,
etc. If there is no suitable scope, you can use \*.
+Every type **except `Chore`** must carry an Issue ID. If no Issue exists for
the change, file one first or reclassify it as `Chore`.
-(3) subject
+### Scope (optional)
-Subject is a short description of the purpose of the commit, no more than 50
characters.
+The module the change touches: `Master`, `Worker`, `API`, `UI`, `TaskPlugin`,
`Dao`, etc. Match a real module name. Omit `[Scope]` when the change is
genuinely cross-cutting (most `Chore` commits).
-##### Body
+### Subject (required)
-The body part is a detailed description of this commit, which can be divided
into multiple lines, and the line break will wrap with 72 characters to avoid
automatic line wrapping affecting the appearance.
+A short imperative sentence describing the change.
-Note the following points in the Body section:
+- Use the imperative mood: *Add*, *Fix*, *Remove* — not *Added* / *Adds*.
+- State the **purpose**, not the implementation detail. The diff already shows
the *how*.
+- No trailing period.
-- Use the verb-object structure, note the use of present tense. For example,
use change instead of changed or changes
+### Body (optional, recommended for non-trivial changes)
-- Don't capitalize the first letter
+When the change is not self-evident from the Subject, add a bullet list of the
main changes. Keep it tight — one line per change point. Lengthy rationale,
design notes, or testing plans go in the **Pull Request description** (see
[PULL_REQUEST_TEMPLATE.md](https://github.com/apache/dolphinscheduler/blob/dev/.github/PULL_REQUEST_TEMPLATE.md)),
not in the commit message.
-- The end of the sentence does not need a ‘.’ (period)
+### Footer (optional)
-##### Footer
+- `BREAKING CHANGE: <description>` — for incompatible changes. Required if the
change breaks RPC, DB schema, or public API compatibility. Also add an entry to
`docs/docs/en/guide/upgrade/incompatible.md`.
+- `Closes #1234` — to auto-close the linked issue on merge.
-Footer only works in two situations
+## Examples
-(1) Incompatible changes
+Good:
-If the current code is not compatible with the previous version, the Footer
part starts with BREAKING CHANGE, followed by a description of the change, the
reason for the change, and the migration method.
+```
+[Fix-18201][TaskPlugin] Fix RemoteShell task NullPointerException on empty
stdout
+```
-(2) Close Issue
+```
+[Improvement-18224][API] Migrate EnvironmentService to typed return values
-If the current commit is for a certain issue, you can close the issue in the
Footer section, or close multiple issues at once.
+- Replace Map<String, Object> returns with dedicated DTOs
+- Update controller and unit tests accordingly
+```
-##### For Example
+```
+[Chore][API] Remove deprecated ProjectService#checkProjectAndAuth
+```
```
-[DS-001][docs-en] add commit message
+[Feature-17900][Master] Support task-group priority override at runtime
-- commit message RIP
-- build some conventions
-- help the commit messages become clean and tidy
-- help developers and release managers better track issues
- and clarify the optimization in the version iteration
+- Add priority field to TaskGroupQueue
+- Honor override when dispatching ready tasks
-This closes #001
+Closes #17900
```
-### Reference documents
+Avoid:
+
+- `fix bug` — no type prefix, no scope, no information.
+- `[fix] update master` — wrong casing, missing issue ID, vague subject.
+- `[Improvement][Master] refactor scheduler to use new state machine and also
fix a NPE in worker dispatch and adjust some logs` — multiple unrelated
changes; split into separate commits.
-[Commit message
format](https://cwiki.apache.org/confluence/display/GEODE/Commit+Message+Format)
+## References
-[On commit messages-Peter
Hutterer](http://who-t.blogspot.com/2009/12/on-commit-messages.html)
+-
[PULL_REQUEST_TEMPLATE.md](https://github.com/apache/dolphinscheduler/blob/dev/.github/PULL_REQUEST_TEMPLATE.md)
+- [Pull Request Notice](./pull-request.md)
+- [Apache Geode commit message
format](https://cwiki.apache.org/confluence/display/GEODE/Commit+Message+Format)
+- [On commit messages — Peter
Hutterer](http://who-t.blogspot.com/2009/12/on-commit-messages.html)
-[RocketMQ Community Operation
Conventions](https://mp.weixin.qq.com/s/LKM4IXAY-7dKhTzGu5-oug)
diff --git a/docs/docs/en/contribute/join/pull-request.md
b/docs/docs/en/contribute/join/pull-request.md
index 10b51ba585..4a1580fcea 100644
--- a/docs/docs/en/contribute/join/pull-request.md
+++ b/docs/docs/en/contribute/join/pull-request.md
@@ -82,8 +82,11 @@ Please refer to the commit message section.
[//]: # (DolphinScheduler uses `Spotless` to automatically fix code style and
formatting errors,)
[//]: # (see [Development Environment
Setup](../development-environment-setup.md#code-style) `Code Style`
section for details.)
-DolphinScheduler uses `Spotless` to automatically fix code style and
formatting errors,
-see [Development Environment Setup](../development-environment-setup.md) `Code
Style` section for details.
+DolphinScheduler uses `Spotless` to enforce code style and formatting. It
covers Java sources, `pom.xml`, and Markdown files (including the docs in this
directory).
+
+**Before opening a Pull Request, you must run `./mvnw spotless:apply` locally
and commit the result.** CI runs `./mvnw spotless:check` and will fail the PR
if any file is not formatted.
+
+See [Development Environment Setup](../development-environment-setup.md) `Code
Style` section for details.
### Question
diff --git a/docs/docs/en/contribute/join/submit-code.md
b/docs/docs/en/contribute/join/submit-code.md
index b1e249d338..b1b011cb69 100644
--- a/docs/docs/en/contribute/join/submit-code.md
+++ b/docs/docs/en/contribute/join/submit-code.md
@@ -42,7 +42,9 @@ git checkout -b xxx origin/dev
```
Make sure that the branch `xxx` is building successfully on the latest code of
the official dev branch
-* After modifying the code locally in the new branch, submit it to your own
repository:
+* After modifying the code locally in the new branch, run `./mvnw
spotless:apply` to apply project formatting before committing. CI runs `./mvnw
spotless:check` and will fail the PR if any file is not formatted (see [Pull
Request Code Style](./pull-request.md#pull-request-code-style)).
+
+* Submit it to your own repository:
`git commit -m 'commit content'`
diff --git a/docs/docs/zh/contribute/join/commit-message.md
b/docs/docs/zh/contribute/join/commit-message.md
index 3d8974535e..56166ea329 100644
--- a/docs/docs/zh/contribute/join/commit-message.md
+++ b/docs/docs/zh/contribute/join/commit-message.md
@@ -1,92 +1,91 @@
# Commit Message 须知
-### 前言
+一个好的 commit message 应当一眼说清**改了什么、为什么改**。完整的来龙去脉留给关联的 Issue / Pull Request ——
commit message 本身保持精炼。
-一个好的 commit message
是能够帮助其他的开发者（或者未来的开发者）快速理解相关变更的上下文，同时也可以帮助项目管理人员确定该提交是否适合包含在发行版中。但当我们在查看了很多开源项目的
commit log 后，发现一个有趣的问题，一部分开发者，代码质量很不错，但是 commit message
记录却比较混乱，当其他贡献者或者学习者在查看代码的时候，并不能通过 commit log 很直观的了解
-该提交前后变更的目的，正如 Peter Hutterer 所言：Re-establishing the context of a piece of code
is wasteful. We can’t avoid it completely, so our efforts should go to reducing
it as much as possible. Commit messages can do exactly that and as a result, a
commit message shows whether a developer is a good collaborator.
因此，DolphinScheduler 结合其他社区以及 Apache 官方文档制定了该规约。
+## 格式
-### Commit Message RIP
+```
+[Type-ISSUE_ID][Scope] Subject
-#### 1：明确修改内容
+(可选 body —— 用要点列出主要改动)
-commit message 应该明确说明该提交解决了哪些问题（bug 修复、功能增强等），以便于用户开发者更好的跟踪问题，明确版本迭代过程中的优化情况。
+(可选 footer —— BREAKING CHANGE / Closes #xxx)
+```
-#### 2：关联相应的Pull Request 或者Issue
+Header 必填，body 和 footer 可选。Subject 建议控制在 72 字符内，避免在 GitHub 上被截断。
-当我们的改动较大的时候，commit message 最好能够关联 GitHub 上的相关 Issue 或者 Pull
Request，这样，我们的开发者在查阅代码的时候能够通过关联信息较为迅速的了解改代码提交的上下文情景，如果当前 commit 针对某个
issue，那么可以在 Footer 部分关闭这个 issue。
+### Type（必填）
-#### 3：统一的格式
+| Type | 使用场景
| 是否必须带 Issue ID |
+|---------------|-------------------------------------------------------------------------------------|------------------|
+| `Feature` | 用户可见的新功能
| 是 |
+| `Improvement` | 已有功能的增强（重构、性能、体验优化）
| 是 |
+| `Fix` | Bug 修复
| 是 |
+| `Doc` | 仅文档变动
| 是 |
+| `DSIP` | 实现某个
[DSIP](https://github.com/apache/dolphinscheduler/issues?q=label%3ADSIP) 提案的变更
| 是（对应 DSIP issue） |
+| `Chore` | 构建、CI、测试脚手架、依赖升级、零碎清理
| 否 |
-格式化后的 CommitMessage 能够帮助我们提供更多的历史信息，方便快速浏览，同时也可以直接从 commit 生成 Change Log。
+除 `Chore` 外的所有 type **都必须带上 Issue ID**。如果没有现成 Issue，请先创建一个；否则把它归类为 `Chore`。
-Commit message 应该包括三个部分：Header，Body 和 Footer。其中，Header 是必需的，Body 和 Footer 可以省略。
+### Scope（可选）
-##### header
+变更涉及的模块名：`Master`、`Worker`、`API`、`UI`、`TaskPlugin`、`Dao`
等。请使用真实存在的模块名。当变更确实横跨多个模块（多数 `Chore` commit 属于此类）时可以省略 `[Scope]`。
-Header 部分只有一行，包括三个字段：type（必需）、scope（可选）和 subject（必需）。
+### Subject（必填）
-[DS-ISSUE编号][type] subject
+一句简短的祈使句，描述本次改动。
-(1) type 用于说明 commit 的类别，只允许使用下面7个标识。
+- 使用祈使语气：*Add*、*Fix*、*Remove*，不要用 *Added* / *Adds*。
+- 说**目的**，不要说实现细节 —— *如何改*已经体现在 diff 中。
+- 句末不加句号。
-* feat：新功能（feature）
-* fix：修补bug
-* docs：文档（documentation）
-* style： 格式（不影响代码运行的变动）
-* refactor：重构（即不是新增功能，也不是修改bug的代码变动）
-* test：增加测试
-* chore：构建过程或辅助工具的变动
+### Body（可选，非平凡改动建议写）
-如果 type 为 feat 和 fix，则该 commit 将肯定出现在 Change log
之中。其他情况（docs、chore、style、refactor、test）建议不放入。
+当 Subject 无法自解释时，用要点列出主要改动。保持紧凑，一行一个改动点。详细的设计动机、权衡考量、测试方案应当写在 **Pull Request
描述**里（见
[PULL_REQUEST_TEMPLATE.md](https://github.com/apache/dolphinscheduler/blob/dev/.github/PULL_REQUEST_TEMPLATE.md)），而不是塞进
commit message。
-(2）scope
+### Footer（可选）
-scope 用于说明 commit 影响的范围，比如 server、remote 等，如果没有更合适的范围，你可以用 *。
+- `BREAKING CHANGE: <说明>` —— 用于不兼容变更。当变更破坏 RPC、数据库 schema 或公开 API 兼容性时必须填写，并在
`docs/docs/en/guide/upgrade/incompatible.md` 中追加一条记录。
+- `Closes #1234` —— 合入时自动关闭对应 issue。
-(3) subject
+## 示例
-subject 是 commit 目的的简短描述，不超过50个字符。
+推荐：
-##### Body
+```
+[Fix-18201][TaskPlugin] Fix RemoteShell task NullPointerException on empty
stdout
+```
-Body 部分是对本次 commit 的详细描述，可以分成多行，换行符将以72个字符换行，避免自动换行影响美观。
+```
+[Improvement-18224][API] Migrate EnvironmentService to typed return values
-Body 部分需要注意以下几点：
+- Replace Map<String, Object> returns with dedicated DTOs
+- Update controller and unit tests accordingly
+```
-* 使用动宾结构，注意使用现在时，比如使用 change 而非 changed 或 changes
+```
+[Chore][API] Remove deprecated ProjectService#checkProjectAndAuth
+```
-* 首字母不要大写
+```
+[Feature-17900][Master] Support task-group priority override at runtime
-* 语句最后不需要 ‘.’ (句号) 结尾
+- Add priority field to TaskGroupQueue
+- Honor override when dispatching ready tasks
-##### Footer
+Closes #17900
+```
-Footer只适用于两种情况
+不推荐：
-(1) 不兼容变动
+- `fix bug` —— 没有 type、没有 scope、没有信息量。
+- `[fix] update master` —— 大小写不规范、缺 issue ID、subject 含糊。
+- `[Improvement][Master] refactor scheduler to use new state machine and also
fix a NPE in worker dispatch and adjust some logs` —— 多个无关改动堆在一起，应当拆成多个 commit。
-如果当前代码与上一个版本不兼容，则 Footer 部分以 BREAKING CHANGE 开头，后面是对变动的描述、以及变动理由和迁移方法。
+## 参考资料
-(2) 关闭 Issue
+-
[PULL_REQUEST_TEMPLATE.md](https://github.com/apache/dolphinscheduler/blob/dev/.github/PULL_REQUEST_TEMPLATE.md)
+- [Pull Request 须知](./pull-request.md)
+- [Apache Geode
提交消息格式](https://cwiki.apache.org/confluence/display/GEODE/Commit+Message+Format)
+- [On commit messages —— Peter
Hutterer](http://who-t.blogspot.com/2009/12/on-commit-messages.html)
-如果当前 commit 针对某个issue，那么可以在 Footer 部分关闭这个 issue,也可以一次关闭多个 issue 。
-
-##### 举个例子
-
-[DS-001][docs-zh] add commit message
-
-* commit message RIP
-* build some conventions
-* help the commit messages become clean and tidy
-* help developers and release managers better track issues
- and clarify the optimization in the version iteration
-
-This closes #001
-
-### 参考文档
-
-[提交消息格式](https://cwiki.apache.org/confluence/display/GEODE/Commit+Message+Format)
-
-[On commit messages-Peter
Hutterer](http://who-t.blogspot.com/2009/12/on-commit-messages.html)
-
-[RocketMQ Community Operation
Conventions](https://mp.weixin.qq.com/s/LKM4IXAY-7dKhTzGu5-oug)
diff --git a/docs/docs/zh/contribute/join/pull-request.md
b/docs/docs/zh/contribute/join/pull-request.md
index 3ee6caf75e..b575bf32b7 100644
--- a/docs/docs/zh/contribute/join/pull-request.md
+++ b/docs/docs/zh/contribute/join/pull-request.md
@@ -83,7 +83,10 @@ waste time。
[//]: # (DolphinScheduler使用`Spotless`为您自动修复代码风格和格式问题，)
[//]: # (详情见[开发手册](../development-environment-setup.md#代码风格)`代码风格`一栏。)
-DolphinScheduler使用`Spotless`为您自动修复代码风格和格式问题，
+DolphinScheduler 使用 `Spotless` 来统一代码风格和格式，覆盖范围包括 Java 源文件、`pom.xml` 以及本目录下的
Markdown 文档。
+
+**提交 Pull Request 前，必须先在本地执行 `./mvnw spotless:apply` 并提交格式化结果。** CI 会运行
`./mvnw spotless:check`，任何文件未格式化都会导致 PR 失败。
+
详情见[开发手册](../development-environment-setup.md)`代码风格`一栏。
### 相关问题
diff --git a/docs/docs/zh/contribute/join/submit-code.md
b/docs/docs/zh/contribute/join/submit-code.md
index a53cea6c0f..7586e0e2af 100644
--- a/docs/docs/zh/contribute/join/submit-code.md
+++ b/docs/docs/zh/contribute/join/submit-code.md
@@ -53,7 +53,9 @@ git checkout -b xxx origin/dev
确保分支`xxx`是基于官方dev分支的最新代码
-* 在新建的分支上本地修改代码以后，提交到自己仓库：
+* 在新建的分支上本地修改代码后，先执行 `./mvnw spotless:apply` 应用项目统一格式化，再进行提交。CI 会运行 `./mvnw
spotless:check`，任何文件未格式化都会导致 PR 失败（参见 [Pull Request Code
Style](./pull-request.md#pull-request-code-style)）。
+
+* 提交到自己仓库：
`git commit -m 'commit content'`
