DanielCarter-stack commented on PR #10445:
URL: https://github.com/apache/seatunnel/pull/10445#issuecomment-3846476002
<!-- code-pr-reviewer -->
<!-- cpr:pr_reply_v2_parts {"group": "apache/seatunnel#10445", "part": 1,
"total": 1} -->
### Issue 1: Missing version placeholder replacement instructions
**Location**:
- `docs/en/transforms/sql-udf.md:50-56`
- `docs/zh/transforms/sql-udf.md:50-56`
**Related context**:
- Reference documentation:
`docs/en/introduction/concepts/event-listener.md:156`
**Problem description**:
The modified documentation uses the `${seatunnel.version}` placeholder, but
does not add clear replacement instructions like `event-listener.md`. This will
cause new users to not know they need to replace this placeholder with the
actual version number (e.g., 2.3.10), potentially leading to build failures if
they copy and use it directly.
**Current code**:
```xml
<dependency>
<groupId>org.apache.seatunnel</groupId>
<artifactId>seatunnel-transforms-v2</artifactId>
<version>${seatunnel.version}</version>
<scope>provided</scope>
</dependency>
```
**Potential risks**:
- **Risk 1**: New users may directly copy the `pom.xml` fragment, causing
Maven to be unable to resolve the `${seatunnel.version}` property (if this
property is not defined in pom.xml)
- **Risk 2**: Users may not know which version number to use (runtime
version or compile-time version?)
- **Risk 3**: Users may mistakenly think SeaTunnel will automatically handle
version replacement
**Impact scope**:
- **Direct impact**: All users developing UDF for the first time
- **Indirect impact**: May lead to users asking questions in forum/issue
channels, increasing support costs
- **Affected audience**: Documentation users (Chinese and English users)
**Severity**: MAJOR (medium-high)
**Improvement suggestions**:
Add clear replacement instructions after the code block (reference
`event-listener.md`):
```markdown
```xml
<dependencies>
<dependency>
<groupId>org.apache.seatunnel</groupId>
<artifactId>seatunnel-transforms-v2</artifactId>
<version>${seatunnel.version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.apache.seatunnel</groupId>
<artifactId>seatunnel-api</artifactId>
<version>${seatunnel.version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>com.google.auto.service</groupId>
<artifactId>auto-service</artifactId>
<version>1.0.1</version>
<scope>provided</scope>
</dependency>
</dependencies>
```
> Note: Replace `${seatunnel.version}` with the actual SeaTunnel version
used in your runtime environment (e.g., 2.3.10). You can check the version by
running `seatunnel-version --version`.
```
** Reason**:
1. 与 `event-listener.md` 保持一致，符合项目文档规范
2. 提供明确的操作指导，减少用户困惑
3. 给出版本查询命令，提升用户体验
4. 中英文文档应同步添加此说明
---
# ## Issue 2: No specific error example provided for version mismatch
** Location**:
- `docs/en/transforms/sql-udf.md:42`（问题描述部分）
- `docs/zh/transforms/sql-udf.md:42`
** Related Context**:
- 无直接相关文件
** Issue Description**:
PR 描述中提到了 "class-not-found errors (such as CommonOptions being
moved/removed)"，但文档中未给出具体的错误示例或警告。用户在遇到问题时可能无法快速定位到版本不匹配是根因。
** Current Content**:
仅添加了粗体警告："**Dependency versions should match the runtime environment.**"
** Potential Risks**:
- **风险1**：用户遇到 `ClassNotFoundException` 时可能排查方向错误（如检查 jar 是否放入 lib 目录）
- **风险2**：用户可能不知道版本不匹配的具体表现形式
- **风险3**：问题排查时间增加，影响用户体验
** Impact Scope**:
- **直接影响**：所有遇到版本问题的用户
- **间接影响**：技术支持成本
- **影响面**：文档使用者
** Severity**: MINOR
** Improvement Suggestions**:
在警告文本后添加具体示例：
```markdown
Add these dependencies and provided scope to your maven project.
**Dependency versions should match the runtime environment.**
> Warning: If you compile UDF with version 2.3.2 but run it with SeaTunnel
2.3.10+, you may encounter errors like:
> - `java.lang ClassNotFoundException:
org.apache.seatunnel.api.table.type.CommonOptions`
> - `java.lang.NoSuchMethodError:
org.apache.seatunnel.api.table.SeaTunnelRow.someMethod()`
>
> To avoid these issues, always use the same version as your SeaTunnel
runtime.
```
** Reason**:
1. 提供具体的错误示例，帮助用户快速定位问题
2. 强化警告的重要性
3. 减少重复的问题咨询
---
# ## Issue 3: Lack of explanation for multi-version environment scenarios
** Location**:
- `docs/en/transforms/sql-udf.md:94-95`（部署说明部分）
- `docs/zh/transforms/sql-udf.md:94-95`
** Related Context**:
- 部署相关章节
** Issue Description**:
文档提到 "Package the UDF project and copy the jar to the path:
${SEATUNNEL_HOME}/lib"，但未说明在多版本环境下（如同时有 2.3.10 和 2.3.12 集群）如何处理。用户可能误以为同一个 UDF
jar 可以在多个版本间通用。
** Current Content**:
```markdown
Package the UDF project and copy the jar to the path: ${SEATUNNEL_HOME}/lib.
And if your UDF use third party library, you also need put it to
${SEATUNNEL_HOME}/lib.
If you use cluster mode, you need put the lib to all your node's
${SEATUNNEL_HOME}/lib folder and re-start the cluster.
```
** Potential Risks**:
- **风险1**：用户可能在不同版本集群间共用 UDF jar，导致运行时错误
- **风险2**：用户不理解为什么需要为每个版本重新编译
- **风险3**：升级 SeaTunnel 版本时忘记重新编译 UDF
** Impact Scope**:
- **直接影响**：多环境用户（开发/测试/生产使用不同版本）
- **间接影响**：版本升级过程中的用户
- **影响面**：部分用户场景
** Severity**: MINOR
** Improvement Suggestions**:
在部署说明后添加版本注意事项：
```markdown
Package the UDF project and copy the jar to the path: ${SEATUNNEL_HOME}/lib.
And if your UDF use third party library, you also need put it to
${SEATUNNEL_HOME}/lib.
If you use cluster mode, you need put the lib to all your node's
${SEATUNNEL_HOME}/lib folder and re-start the cluster.
> **Important**: UDF jars are compiled against a specific SeaTunnel version.
If you upgrade SeaTunnel or run multiple versions, you must recompile your UDF
with the matching version for each environment.
```
** Reason**:
1. 明确版本耦合关系
2. 提醒升级时的注意事项
3. 预防多版本环境下的常见错误
---
# ## Issue 4: No explanation on how to verify successful version matching
** Location**:
- 整个文档
** Related Context**:
- 缺少验证相关章节
** Issue Description**:
文档未提供任何验证版本匹配是否成功的方法。用户编译部署后，无法确认 UDF 是否能正常工作，只能等到实际运行时才发现问题。
** Potential Risks**:
- **风险1**：用户可能在测试阶段未发现问题，生产环境才暴露
- **风险2**：缺少快速验证手段，增加调试成本
- **风险3**：用户自信心不足
** Impact Scope**:
- **直接影响**：所有 UDF 开发者
- **间接影响**：测试效率
- **影响面**：文档使用者
** Severity**: MINOR
** Improvement Suggestions**:
在示例章节后添加验证步骤：
```markdown
## Example
[Existing example content...]
## Verification
After deploying your UDF, you can verify it works correctly by:
1. Check if the UDF is loaded successfully in the logs:
```
Successfully loaded UDF: com.example.ExampleUDF
```
2. Run a simple test query to ensure the UDF executes without
`ClassNotFoundException` or `NoSuchMethodError`.
3. If you encounter version mismatch errors, verify your pom.xml uses the
same version as your SeaTunnel runtime.
```
**Rationale**:
1. Provide verification means to enhance user confidence
2. Help users quickly discover version issues
3. Complete documentation integrity
---
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
