Apache Yetus 快速入门与集成示例

一、快速入门路径

本篇用两个最小闭环带您上手 Apache Yetus 0.15.1：

releasedocmaker：从 JIRA 生成 CHANGELOG 与 RELEASENOTES（发布文档闭环）；
test-patch：对一个本地 git 仓库的功能分支补丁执行预提交审计（质量审计闭环）。

安装本身请参考《Ubuntu 22.04 安装 Apache Yetus 指南》或《CentOS 8 安装 Apache Yetus 指南》，本文假设 releasedocmaker、test-patch 已在 PATH 中且版本为 0.15.1。

先确认环境：

releasedocmaker -V
test-patch --version

实测回显：

0.15.1
0.15.1

二、准备演示仓库

2.1 创建仓库与提交

创建一个纯 shell 的演示项目，按 Conventional Commits 规范提交：

git config --global user.name demo
git config --global user.email demo@example.com
mkdir -p /opt/demo-shell && cd /opt/demo-shell
git init -q
git checkout -qb main

cat > build.sh <<'EOF'
#!/usr/bin/env bash
# build demo script
set -e
echo hello
EOF
git add -A
git commit -q -m "feat: add initial build script"

sed -i 's/echo hello/echo "hello world"/' build.sh
git add -A
git commit -q -m "fix: correct greeting message in build script"

再拉出功能分支，制造一个带 shellcheck 缺陷的提交（$1 未加引号会触发 SC2086）：

git checkout -qb feature/patch
cat > build.sh <<'EOF'
#!/usr/bin/env bash
# build demo script
set -e
echo "hello world"
# extra feature
ls $1
EOF
git add -A
git commit -q -m "feat: add extra feature line"
git checkout -q main

确认提交历史（实测回显）：

26259c6 feat: add extra feature line
06d7dda fix: correct greeting message in build script
4a9d3ef feat: add initial build script

2.2 导出补丁

切回 main 基线，将 feature/patch 的增量导出为标准补丁文件：

git format-patch main..feature/patch --stdout > /tmp/demo.patch
wc -l /tmp/demo.patch

实测回显：

22 /tmp/demo.patch

注意方向必须在 main 上导出 main..feature/patch；方向写反会得到空补丁（见第八章 Q4）。

三、releasedocmaker 生成发布文档

3.1 运行

releasedocmaker 的数据源是 JIRA（0.15.1 不支持直接读取 git 提交记录生成文档，本地仓库仅作为输出目录）。这里用 Apache JIRA 上真实存在的 YETUS 项目做全链路验证：

cd /opt/demo-shell
releasedocmaker --project YETUS --version 0.15.1 \
  --outputdir /tmp/rdm-yetus \
  --projecttitle 'Apache Yetus' --index
echo "exit=$?"

实测回显：

exit=0

3.2 输出目录结构

ls -la /tmp/rdm-yetus/

实测回显：

total 16
-rw-r--r-- 1 root root 1424 Oct 12 14:38 CHANGELOG.md
-rw-r--r-- 1 root root    0 Oct 12 14:38 README.md
-rw-r--r-- 1 root root 1227 Oct 12 14:38 RELEASENOTES.md
-rw-r--r-- 1 root root    0 Oct 12 14:38 index.md

CHANGELOG.md：按 issue 类型分节的完整变更表（含 JIRA 链接、优先级、组件、报告人、贡献者）；
RELEASENOTES.md：面向发布公告的摘要列表；
README.md 与 index.md：单版本 + --index 场景下实测为空文件，多版本 + --fileversions/--dirversions 时才有索引内容。

3.3 生成内容展示

CHANGELOG.md 开头（实测原文）：

# Apache Yetus Changelog

  ## Release 0.15.1 - 2025-02-16



### BUG FIXES:

| JIRA | Summary | Priority | Component | Reporter | Contributor |
|:---- |:---- | :--- |:---- |:---- |:---- |
| [YETUS-1249](https://issues.apache.org/jira/browse/YETUS-1249) | fix macos tests in yetus-homebrew |  Major | homebrew | Allen Wittenauer | Allen Wittenauer |


### OTHER:

| JIRA | Summary | Priority | Component | Reporter | Contributor |
|:---- |:---- | :--- |:---- |:---- |:---- |
| [YETUS-1247](https://issues.apache.org/jira/browse/YETUS-1247) | Update dependencies for 2024-10 |  Major | build, github-action | Allen Wittenauer | Allen Wittenauer |
| [YETUS-1248](https://issues.apache.org/jira/browse/YETUS-1248) | create workflow\_dispatch to all workflows |  Major | build | Allen Wittenauer | Allen Wittenauer |
| [YETUS-1250](https://issues.apache.org/jira/browse/YETUS-1250) | Upgrade nodejs |  Major | build | Allen Wittenauer | Allen Wittenauer |

RELEASENOTES.md 开头（实测原文）：

# Apache Yetus  0.15.1 Release Notes

These release notes cover new developer and user-facing incompatibilities, important issues, features, and major improvements.


---

* [YETUS-1247](https://issues.apache.org/jira/browse/YETUS-1247) | *Major* | **Update dependencies for 2024-10**

3.4 接入自有 JIRA

自建 JIRA 的项目用 --baseurl 指向实例地址即可，其余参数不变：

releasedocmaker --project MYPROJ --version 1.0.0 \
  --baseurl https://jira.example.com \
  --outputdir ./output --projecttitle 'My Project'

将上述命令放入发布流水线的打包阶段，即可实现发布文档自动生成。

四、test-patch 最小审计示例

4.1 运行审计

对 /tmp/demo.patch 执行最小审计（离线模式，仅启用 shell 相关插件）：

cd /opt/demo-shell
test-patch --project=demo \
  --basedir=/opt/demo-shell \
  --patch-dir=/tmp/tp-out \
  --plugins=shellcheck,shelldocs,blanks,test4tests \
  --build-tool=nobuild \
  --offline \
  /tmp/demo.patch
echo "exit=$?"

实测报告全文关键内容：

-1 overall

 _____     _ _                _
|  ___|_ _(_) |_   _ _ __ ___| |
| |_ / _` | | | | | | '__/ _ \ |
|  _| (_| | | | |_| | | |  __/_|
|_|  \__,_|_|_|\__, | |___|
|____/

| Vote |      Subsystem |  Runtime   | Comment
============================================================================
+---------------------------------------------------------------------------
|      |                |            | Prechecks
+---------------------------------------------------------------------------
+---------------------------------------------------------------------------
|      |                |            | main Compile Tests
+---------------------------------------------------------------------------
+---------------------------------------------------------------------------
|      |                |            | Patch Compile Tests
+---------------------------------------------------------------------------
|  +1  |        blanks  |   0m  0s   | The patch has no blanks issues.
|  -1  |    shellcheck  |   0m  1s   | The patch generated 1 new + 0 unchanged
|      |                |            | - 0 fixed = 1 total (was 0)
|  +1  |     shelldocs  |   0m  0s   | No new issues.
+---------------------------------------------------------------------------
|      |                |            | Other Tests
+---------------------------------------------------------------------------
|      |                |   0m  1s   |


|| Subsystem || Report/Notes ||
============================================================================
|  shellcheck  | /tmp/tp-out/results-shellcheck.txt |
| Optional Tests | shellcheck shelldocs |
| Build tool | nobuild |
| git revision | main / 06d7dda3610d85e8e091870376c12074d0043bbe |
| modules | C: . U: . |
| versions | git=2.34.1 shellcheck=0.8.0 |
| Powered by | Apache Yetus 0.15.1 https://yetus.apache.org |


============================================================================
                              Finished build.
============================================================================

退出码实测为 1（存在 -1 投票），可直接用作流水线卡点。

4.2 结果解读

整体投票 -1 由 shellcheck 插件贡献：补丁新增 1 个问题（build.sh 第 6 行 ls $1 未加引号，SC2086）；
明细文件 /tmp/tp-out/results-shellcheck.txt 实测内容：

build.sh:6:4: note: Double quote to prevent globbing and word splitting. [SC2086]

patch-dir 下的 input.patch、gitdiffcontent.txt、results-*.txt 等文件可用于归档与复盘；
修复缺陷后重新导出补丁再审计，shellcheck 投票即恢复 +1。

4.3 集成到流水线

典型接入方式（以 Shell 脚本阶段为例）：

git format-patch "${BASE_BRANCH}..HEAD" --stdout > /tmp/pr.patch
test-patch --project=myproj \
  --basedir="$(pwd)" \
  --patch-dir=/tmp/tp-"$BUILD_ID" \
  --plugins=shellcheck,shelldocs,blanks,test4tests \
  --build-tool=nobuild \
  --offline \
  --console-report-file=/tmp/report.txt \
  /tmp/pr.patch

建议固定 BASE_BRANCH（如 main）、固定插件清单，并把 --console-report-file 产物归档。涉及 Maven/Gradle 的项目，将 --build-tool 换为 maven/gradle 并按项目规模设置 MAVEN_OPTS（如 -Xmx2g）。

五、personality 定制示例

在仓库创建 .yetus/personality.sh 即可被 test-patch 自动加载：

mkdir -p .yetus
cat > .yetus/personality.sh <<'EOF'
#!/usr/bin/env bash
# Demo personality: only enable shell checkers
personality_plugins "shellcheck,shelldocs,blanks"

function personality_parse_args
{
  echo "demo personality: no extra args"
}

function personality_globals
{
  YetusYetusPersonalityFlag=1
}
EOF
git add .yetus
git commit -q -m "chore: add yetus personality"

重新运行第四章的审计命令，实测报告尾表出现：

| Personality | /opt/demo-shell/.yetus/personality.sh |

运行日志出现：

demo personality: no extra args

实测重要提示：0.15.1 中仅靠 personality_plugins 顶部调用并不能真正启用插件（插件注册早于 personality 加载），报告 Optional Tests 仍为空。请以命令行 --plugins 显式传参为准，personality 用于模块与文件级规则定制。

六、输出与工作目录速查

路径	内容
--outputdir 指定目录	CHANGELOG.md、RELEASENOTES.md、README.md、index.md
--patch-dir 指定目录	input.patch（导入的补丁）、gitdiffcontent.txt（补丁内容）、results-.txt（各插件明细）、branch--result.txt（基线对照结果）
控制台报告	投票表 + 尾表（版本、构建工具、插件清单）
--console-report-file	控制台报告的文件副本

七、常见问题

Q1： releasedocmaker 报 "This script requires python-dateutil module"？

定位：Python 依赖缺失。解决：pip3 install python-dateutil（Ubuntu 上用 python3 -m pip install python-dateutil）。

Q2： releasedocmaker 报 "JIRA returns HTTP error 400 ... does not exist for the field 'project'"？

定位：--project 项目名在目标 JIRA 上不存在。解决：换用真实项目名；自建实例加 --baseurl。

Q3： test-patch 报 "can't run in a workspace that contains the following modifications"？

定位：工作区有未提交修改或未跟踪文件（包括新建的 .yetus 目录未入库）。解决：提交或还原后再跑，或临时加 --dirty-workspace。

Q4： test-patch 运行"成功"但没有任何测试投票？

定位一：--format-patch 导出方向反了，补丁为空文件（实测空补丁时报告仍显示 +1 overall 但 Optional Tests 为空）；定位二：未传 --plugins（0.15.1 默认不启用任何插件）。解决：在基线分支用 git format-patch main..feature/patch --stdout 导出并核对文件非空；命令中显式加 --plugins。

Q5： 提示 "patch does not apply to feature/patch. Rebase required? Wrong Branch?"？

定位：当前检出分支与补丁基线不一致。解决：切回基线分支（git checkout main）再运行审计。

Q6： 审计结束后 git status 显示 build.sh 仍处于修改状态？

定位：默认运行模式结束后不强制还原仓库（nobuild 构建工具的清理动作是空操作）。解决：git checkout -- build.sh 还原；或运行时加 --resetrepo 自动还原。

Q7： --plugins=all 报 "error: No such remote 'origin'" 后无报告？

定位：all 会启用 github/jira 等问题系统插件，无远程与凭据时初始化失败。解决：最小环境按需列出测试类插件，勿用 all。

八、参考链接

Apache Yetus 官方下载页：https://yetus.apache.org/downloads/
Apache Yetus 官方文档首页：https://yetus.apache.org/
releasedocmaker 官方文档：https://yetus.apache.org/documentation/in-progress/releasedocmaker
test-patch 官方文档：https://yetus.apache.org/documentation/in-progress/precommit/
precommit-patchnames 补丁命名规范：https://yetus.apache.org/documentation/in-progress/precommit-patchnames
Conventional Commits 规范：https://www.conventionalcommits.org/zh-hans/
GitHub 仓库：https://github.com/apache/yetus