diff --git a/.gitignore b/.gitignore index 482e117f35bf..ff6e43c4161b 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 d5e10261b67c..652184ba0dc1 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 0e224aa987ae..3884913e8ded 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 intuitively understood through commit log. -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: ` — 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 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 10b51ba58530..4a1580fceaea 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 b1e249d338ba..b1b011cb69b2 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 3d8974535e96..56166ea3292c 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 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 3ee6caf75e3d..b575bf32b7b7 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 a53cea6c0f53..7586e0e2af9a 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'`