This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
The following commit(s) were added to refs/heads/dev by this push:
new 4533d3181b [Docs] Add performance contribution guide (#12214)
4533d3181b is described below
commit 4533d3181bf3d205a01741aa353b7a02307cb144
Author: zhiweiniu <[email protected]>
AuthorDate: Wed Sep 9 01:27:57 2026 +0000
[Docs] Add performance contribution guide (#12214)
---
docs/en/developer/contribute-performance-guide.md | 96 +++++++++++++++++++++++
docs/en/developer/contribution-path.md | 15 ++++
docs/sidebars.js | 1 +
docs/zh/developer/contribute-performance-guide.md | 87 ++++++++++++++++++++
docs/zh/developer/contribution-path.md | 15 ++++
5 files changed, 214 insertions(+)
diff --git a/docs/en/developer/contribute-performance-guide.md
b/docs/en/developer/contribute-performance-guide.md
new file mode 100644
index 0000000000..8295e29e8d
--- /dev/null
+++ b/docs/en/developer/contribute-performance-guide.md
@@ -0,0 +1,96 @@
+---
+title: Contribute Performance Improvements
+---
+
+# Contribute Performance Improvements
+
+SeaTunnel welcomes contributions that improve performance for representative
workloads or fix
+measured regressions. Performance work benefits from early, open discussion
and evidence that
+others can reproduce. A benchmark can reveal a regression or test a suspected
cause, but a faster
+microbenchmark alone does not establish a benefit to users.
+
+```text
+Observe a problem → discuss scope → reproduce → optimize → compare → review
trade-offs
+```
+
+## Build Community Consensus
+
+Before substantial implementation, open or reuse a [GitHub
Issue](https://github.com/apache/seatunnel/issues)
+and describe:
+
+- the affected workload and SeaTunnel execution path;
+- the observed effect on throughput, latency, resource use, or job stability;
+- the environment and evidence used to observe the problem;
+- the expected benefit and proposed scope.
+
+The initial report does not need a finished benchmark. It should contain
enough evidence for the
+community to discuss whether the problem is relevant, whether the proposed
experiment represents a
+useful SeaTunnel workload, and whether the scope is appropriate. Use the
+[dev mailing
list](https://lists.apache.org/[email protected]) when the
change affects
+multiple modules, introduces a lasting maintenance commitment, or needs a
broader design decision.
+
+A measured speedup contributes evidence to that discussion; it does not decide
the outcome by
+itself. The community also considers correctness, compatibility, other
workloads, resource
+trade-offs, implementation complexity, and maintenance cost.
+
+## Build a Reproducible Benchmark
+
+Choose a workload that represents the reported problem and reaches the
affected production path.
+Define the logical operation, input shape, concurrency, warmup, measurement
duration, and timed
+boundary. Explain how these choices relate to actual SeaTunnel workloads.
Frequent calls, a high CPU
+share, or lock samples do not prove a bottleneck by themselves.
+
+Keep fixture construction and result validation outside the timed region
unless they are the subject
+of the test.
+
+Validate the output so an incomplete operation cannot appear faster by doing
less work. Run enough
+repetitions to show normal variation, and report representative results rather
than selecting the
+best run. Test relevant input sizes and concurrency levels, including cases
that may regress. Make
+resource trade-offs explicit; for example, higher throughput obtained by using
more memory may not
+be an improvement for every workload.
+
+See [Zeta Benchmark](../engines/zeta/benchmark.md) for local execution and
profiling commands.
+
+## Add a Benchmark
+
+Reuse an existing benchmark when it represents the problem. A new benchmark
should have:
+
+- a workload that reaches the affected production path;
+- deterministic fixtures and output validation;
+- bounded runtime and results stable enough to detect a useful change.
+
+For the current `Benchmarks` workflow, both revisions build their own
benchmark module. A benchmark
+that exists only in the optimization PR cannot run on the baseline revision.
Propose a new benchmark
+in a focused PR first so the community can review the workload and measurement
independently. After
+it merges into `dev`, create the optimization branch from a revision that
contains it. Merging the
+benchmark establishes a shared experiment; it does not predetermine the
outcome of a later proposal.
+
+:::caution Compare the Same Experiment
+
+Baseline and Candidate must use the same benchmark code, fixtures, parameters,
JDK, and measurement
+boundary. If any of them differ, the result cannot isolate the production-code
change.
+
+:::
+
+## Submit and Measure the Performance Fix
+
+Keep the benchmark and its parameters unchanged while implementing the
optimization. Run the
+`Benchmarks` workflow with:
+
+- `seatunnel_ref` set to the exact baseline commit;
+- `pr_number` set to the performance-fix PR;
+- the same benchmark method, parameters, and JDK for both revisions.
+
+Use an unprofiled comparison to quantify improvement or regression. Profiling
can help explain the
+cause, but profiler overhead makes its Score unsuitable for the comparison.
+
+## Share Evidence and Trade-offs
+
+Include the following in the performance-fix PR:
+
+- Baseline and Candidate commit SHAs;
+- the exact benchmark method and workload parameters;
+- JDK, JVM settings, and relevant machine information;
+- the comparison report, raw JMH results, and variation across runs;
+- correctness and compatibility checks for the changed path;
+- regressions, resource trade-offs, and anything the experiment does not
verify.
diff --git a/docs/en/developer/contribution-path.md
b/docs/en/developer/contribution-path.md
index e675fbca3f..b60c4985c6 100644
--- a/docs/en/developer/contribution-path.md
+++ b/docs/en/developer/contribution-path.md
@@ -21,6 +21,7 @@ Use this page if you want to:
- fix a documentation issue
- contribute a connector or transform
+- investigate and fix a performance problem
- fix a bug
- understand where to ask questions before opening a PR
@@ -71,6 +72,19 @@ Start here:
- [Transform Plugin System](../architecture/transform-plugin-system.md)
- [Transforms Catalog](../transforms)
+### Performance Contribution
+
+Best first steps:
+
+- start from an observed problem or measured regression, not an arbitrary
hot-looking method
+- discuss the workload, evidence, and expected benefit with the community
before substantial implementation
+- contribute a reproducible benchmark before submitting the optimization
+
+Start here:
+
+- [Contribute Performance Improvements](./contribute-performance-guide.md)
+- [Zeta Benchmark](../engines/zeta/benchmark.md)
+
### Code or Architecture Contribution
Best first steps:
@@ -165,4 +179,5 @@ Pick one path based on your goal:
- docs path: [Docs Format Specification](./docs-format-specification.md) ->
[Getting Started Overview](../getting-started/overview.md)
- connector path: [How to Create Your
Connector](./how-to-create-your-connector.md) -> [Source Connector
Development](./source-connector-development.md) or [Sink Connector
Development](./sink-connector-development.md)
- transform path: [Contribute Transform-V2
Plugins](./contribute-transform-v2-guide.md) -> [Transform Plugin
System](../architecture/transform-plugin-system.md)
+- performance path: [Contribute Performance
Improvements](./contribute-performance-guide.md) -> [Zeta
Benchmark](../engines/zeta/benchmark.md)
- engine path: [Set Up Develop Environment](./setup.md) -> [Architecture
Overview](../architecture/overview.md)
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 138386fb9e..2c7b952222 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -404,6 +404,7 @@ const sidebars = {
"developer/sink-connector-development",
"developer/contribute-plugin",
"developer/contribute-transform-v2-guide",
+ "developer/contribute-performance-guide",
"developer/docs-format-specification",
"developer/new-license"
]
diff --git a/docs/zh/developer/contribute-performance-guide.md
b/docs/zh/developer/contribute-performance-guide.md
new file mode 100644
index 0000000000..8ad0fdfce0
--- /dev/null
+++ b/docs/zh/developer/contribute-performance-guide.md
@@ -0,0 +1,87 @@
+---
+title: 贡献性能优化
+---
+
+# 贡献性能优化
+
+SeaTunnel 欢迎针对典型负载的性能优化，以及对已测得性能回退的修复。性能工作应尽早公开讨论，
+并提供他人能够复现的证据。Benchmark 可以发现回退，也可以验证对根因的判断，但微基准变快
+本身不能证明用户能够获得收益。
+
+```text
+发现问题 → 讨论范围 → 受控复现 → 实现优化 → 对比结果 → 评估取舍
+```
+
+## 形成社区共识
+
+在开始较大的实现之前，请创建或复用 [GitHub Issue](https://github.com/apache/seatunnel/issues)，
+并说明：
+
+- 受影响的负载和 SeaTunnel 执行路径；
+- 对吞吐、延迟、资源消耗或作业稳定性的影响；
+- 观察问题时使用的环境和证据；
+- 预期收益和计划修改的范围。
+
+最初的报告不需要包含完整 Benchmark，但应提供足够证据，供社区讨论问题是否值得解决、计划中的
+实验能否代表有意义的 SeaTunnel 负载，以及改动范围是否合适。如果改动涉及多个模块、带来长期
+维护责任或需要更广泛的设计决策，请使用 [dev
邮件列表](https://lists.apache.org/[email protected])
+进行讨论。
+
+测得性能提升是社区讨论中的一项证据，不能单独决定结果。社区还会考虑正确性、兼容性、其他
+负载、资源取舍、实现复杂度和长期维护成本。
+
+## 构建可复现的 Benchmark
+
+选择能够代表所报告问题并触达受影响生产路径的负载。明确逻辑操作、输入形态、并发度、预热、
+测量时长和计时边界，并说明这些选择与实际 SeaTunnel 负载的关系。方法调用频繁、CPU 占比较高
+或出现锁样本，本身都不能证明该路径是瓶颈。
+
+除非 Fixture 构建或结果校验本身就是测试目标，否则应将它们放在计时范围之外。
+
+必须校验输出，避免操作因为少做了工作而显得更快。执行足够多轮，展示正常波动范围，并报告
+具有代表性的结果，而不是只挑最好的一次。测试相关的输入规模和并发度，包括可能出现回退的
+场景。资源取舍也必须明确，例如通过增加内存获得的吞吐提升并不一定适合所有负载。
+
+本地运行和 Profiling 命令见 [Zeta 基准测试](../engines/zeta/benchmark.md)。
+
+## 添加 Benchmark
+
+如果已有 Benchmark 能够代表问题，应优先复用。新增 Benchmark 应满足：
+
+- 负载能够触达受影响的生产路径；
+- Fixture 确定，且包含结果校验；
+- 运行时间可控，结果足够稳定，可以识别有意义的变化。
+
+当前 `Benchmarks` Workflow 会在两个版本中分别构建各自的 Benchmark 模块。如果 Benchmark
+只存在于优化 PR，Baseline 版本就无法运行它。因此，应先用一个聚焦的 PR 提议新 Benchmark，
+让社区可以独立审查负载和测量方法。合入 `dev` 后，再从包含该 Benchmark 的版本创建优化分支。
+合入 Benchmark 是为了建立共同的实验基础，并不预先决定后续提案的结果。
+
+:::caution 两个版本必须运行相同的实验
+
+Baseline 和 Candidate 必须使用相同的 Benchmark 代码、Fixture、参数、JDK 和测量边界。
+其中任何一项不同，结果都无法单独说明生产代码改动带来的影响。
+
+:::
+
+## 提交并测量性能修复
+
+实现优化时，保持 Benchmark 及其参数不变。运行 `Benchmarks` Workflow 时：
+
+- `seatunnel_ref` 填写精确的 Baseline Commit；
+- `pr_number` 填写性能修复 PR 编号；
+- 两个版本使用相同的 Benchmark 方法、参数和 JDK。
+
+使用不带 Profiler 的对比量化性能改善或回退。Profiling 可以帮助解释原因，但它引入的额外
+开销使其 Score 不适合作为对比结果。
+
+## 分享证据和取舍
+
+在性能修复 PR 中附上：
+
+- Baseline 和 Candidate Commit SHA；
+- 精确的 Benchmark 方法和负载参数；
+- JDK、JVM 设置和相关机器信息；
+- 对比报告、原始 JMH 结果和多轮运行的波动范围；
+- 针对改动路径的正确性和兼容性检查；
+- 发现的回退、资源取舍，以及实验未能验证的内容。
diff --git a/docs/zh/developer/contribution-path.md
b/docs/zh/developer/contribution-path.md
index 342233637c..8dab6944dd 100644
--- a/docs/zh/developer/contribution-path.md
+++ b/docs/zh/developer/contribution-path.md
@@ -21,6 +21,7 @@ title: 贡献路径
- 修文档
- 贡献 connector 或 transform
+- 定位并修复性能问题
- 修一个 bug
- 想先知道应该去哪里提问、再决定要不要提 PR
@@ -71,6 +72,19 @@ title: 贡献路径
- [Transform 插件体系](../architecture/transform-plugin-system.md)
- [Transforms 目录](../transforms)
+### 性能贡献
+
+比较好的起点包括：
+
+- 从已观察到的问题或测得的性能回退出发，而不是随意选择看起来繁忙的方法
+- 在开始较大的实现之前，先与社区讨论负载、证据和预期收益
+- 先贡献可复现的 Benchmark，再提交性能优化
+
+建议先看：
+
+- [贡献性能优化](./contribute-performance-guide.md)
+- [Zeta 基准测试](../engines/zeta/benchmark.md)
+
### 代码或架构贡献
比较好的起点包括：
@@ -165,4 +179,5 @@ workflow 按下面的规则选择 jobs：
- 文档路径：[文档格式规范](./docs-format-specification.md) ->
[快速入门总览](../getting-started/overview.md)
- connector 路径：[开发自己的 Connector](./how-to-create-your-connector.md) -> [Source
Connector 开发指南](./source-connector-development.md) 或 [Sink Connector
开发指南](./sink-connector-development.md)
- transform 路径：[贡献 Transform-V2 插件](./contribute-transform-v2-guide.md) ->
[Transform 插件体系](../architecture/transform-plugin-system.md)
+- 性能路径：[贡献性能优化](./contribute-performance-guide.md) -> [Zeta
基准测试](../engines/zeta/benchmark.md)
- 引擎路径：[搭建开发环境](./setup.md) -> [架构概览](../architecture/overview.md)
