【免费下载链接】foo_openlyrics
An open-source lyric display panel for foobar2000
HTML Tidy 是一款久经考验的 HTML 语法检查与清洗工具，在 foo_openlyrics 项目中以 5.8.0 版本内嵌于 3rdparty/tidy-html5-5.8.0，既提供tidy命令行工具，也提供可供二次开发的 LibTidy 库。本文以官方贡献文档 README/CONTRIBUTING.md 为骨架，结合仓库内真实源码与回归测试资源，系统讲解如何规范地提交问题报告、搭建 Git 工作流、跑通回归测试并提交一个合格的 Pull Request，读完即可将这套贡献流程直接套用到其他开源项目。
引言：为什么需要一份贡献规范
HTML Tidy 自诞生以来长期活跃，从 version.txt 可见当前仓库锁定在 5.8.0 / 2021.07.10 版本。这样一个维护多年的项目，代码量庞大、平台差异复杂（Windows、macOS、Linux），任何一处修改都可能影响已有的解析行为。正因如此，官方在 README/CONTRIBUTING.md 中沉淀了一套“先报告、后修改、再验证”的协作规范：既要保证维护者能快速复现问题，也要保证每一个改动都有回归测试兜底。仓库目录下与之配套的 README/BUILD.md、README/CODESTYLE.md、README/TESTING.md 以及 regression_testing 子目录，共同构成了这套规范的可执行细节。
第一步：先学会"提问"——高质量问题报告的写法
贡献文档明确指出，如果你只是在使用tidy命令行或在自己的项目里调用 LibTidy API 时遇到困难，不要急于改代码，而是先在 Issue 讨论区搜索、提问。提问前请务必用不同关键词多做几次检索，确认不是重复问题；如果此前已有类似讨论但你确信场景不同，要在新帖中附上相关旧帖的引用。
为了让维护者能快速复现，问题报告需要包含以下六项要素：
| 要素 | 说明 |
|---|---|
| 版本号 | 运行tidy -v获取 |
| 配置 | 当时使用的 Tidy 配置 |
| 输入样本 | 一段尽可能小的 HTML 输入 |
| 实际输出 | 运行得到的输出 |
| 期望输出 | 你认为正确的结果 |
| 示例代码 | 如果是 API 问题，附上最小调用代码 |
其中，提供的 HTML 样本最好能通过 W3C 官方校验器，因为 Tidy 的目标就是尽可能贴合当前 W3C 标准，一个能通过校验的样本可以排除“输入本身不合法”的干扰。
在 foo_openlyrics 中的实际印证：本项目正是以 LibTidy API 方式集成 Tidy 的典型用户。src/sources/lyric_source.cpp 中LyricSourceRemote::load_html_document依次调用tidyCreate、tidySetErrorBuffer、tidyOptSetBool、tidyParseString、tidyCleanAndRepair、tidyRunDiagnostics、tidySaveBuffer，并将解析结果交给 pugixml 的doc.load_buffer。如果你在类似集成中遇到“输出和预期不符”的问题，把上面这段调用序列、输入的 HTML 片段和期望的清洗结果一起贴出来，就是一份合格的 API 问题报告。
第二步：决定改什么——哪些改动适合提 PR
文档建议优先考虑以下五类改动提交 Pull Request：
- 新功能（New features）
- Bug 修复（Bug fixes）
- 低效代码块（Inefficient blocks of code）
- 内存问题（Memory problems）
- 语言翻译（Language translations）
如果问题涉及程序构建方式或代码风格取向等更深层的设计决策，文档建议先创建 Issue 讨论，再动手写 PR，避免投入精力后方案被否。新功能同样如此——先了解项目方向、已有 PR 和已开/已关的 Issue，再动手。
代码风格方面，文档要求对照 README/CODESTYLE.md，但更强调的是“以现有代码为准”。从该文档可见 Tidy 的既有约定包括：4 空格缩进、不用 Tab；不使用//单行注释；左花括号换行缩进；声明中指针操作符须位于宏文档注释之前等。从源码结构看，Tidy 的 C 代码（如 src/parser.c、src/tidylib.c）正是这些约定的忠实体现，新代码向它们看齐即可。
第三步：Git 工作流——Fork、分支与多分支隔离
贡献文档给出了一套标准 GitHub 协作流程：
- 将 tidy 仓库 Fork 到自己的 GitHub 账号（右上角
Fork按钮）； - 可选：生成 SSH Key 并添加到账号的 SSH and GPG keys 设置；
- 克隆自己的 Fork：
git clone git@github.com:<name>/tidy-html5.git [tidy-fork]（也可用 HTTPS）； - 创建分支：
cd tidy-fork; git checkout -b <branch-name>； - 在该分支上编辑并提交；
- 测试改动，必要时运行回归测试；
- 推送分支：
git push -u origin <branch-name>； - 创建 Pull Request；
- 等待维护者评论与合并。
提交信息规范：一般建议频繁提交，并为每个提交附上说明性信息，如git commit -m "Is. #NNN - reason for change" <file[s]>，把 Issue 编号写进提交信息有助于 PR 评审时追溯。当然规则并非一刀切——例如新增一个命令行选项往往要同时改多个文件，此时把大量相关编辑合并进一个提交反而更合适。
多分支隔离：如果你要修改多个互不依赖的事项，请使用不同的分支，并在创建新分支前切回next分支。否则 GitHub 会把同一分支上的所有提交合并进一个 PR，导致互不相关的内容被捆绑评审。
同步上游：保持next分支与 upstream 一致
文档特别强调保持 fork 的next分支与上游同步“非常重要”，给出了完整的同步命令序列：
git remote add upstream git@github.com:htacg/tidy-html5.git # 只需执行一次 git checkout next git status git stash # 若工作区不干净 git fetch upstream git rebase upstream/next git stash pop # 若需要，解决冲突 git push # 更新 fork 的 next 分支其他分支也要重复类似操作：git checkout <your-branch>→git rebase next→ 解决冲突 →git push。文档坦言“同时维护多个分支并时刻跟上活跃的 upstream 并不轻松”，这正是建议尽量用小而聚焦的 PR 的原因。
第四步：回归测试——质量控制的最后防线
文档明确指出：代码改动必须跑回归测试。Tidy 的回归测试体系非常独特——测试用例存放在独立的仓库tidy-html5-tests中，因此你需要先克隆（或 Fork 后克隆）它，最好放在与tidy-html5、你的tidy-fork同级的根目录下。在本仓库中，可以查看 regression_testing/README.md 了解完整规范，其cases/目录下实际包含了access-*、github-*、legacy-*、xml-*等多组测试集（见 regression_testing/cases）。
Unix 下的运行方式
git clone git@github.com:htacg/tidy-html5-tests.git cd tidy-html5-tests/tools-sh ./testall.sh ../../tidy-fork/build/cmake/tidy diff -u ../cases/testbase-expects ../cases/testbase-results第一行克隆测试仓库；第二行进入 Unix 工具脚本目录；第三行用你新编译的 tidy 可执行文件运行全部测试；最后用diff对比“期望输出”目录与“实际结果”目录。Windows 平台则使用tools-cmd目录下的alltest.bat，可运行alltest.bat --help查看用法。
测试结果如何解读
如果测试暴露出不同的退出码，或expects与results之间存在差异，必须逐条仔细研究核对。可能存在你的新结果是正确的情况——此时必须为测试仓库同时提交一个配套 PR，与源码 PR 一一对应，否则维护者无法合并。
有两个雷区必须避开：
- 不要改动源码仓库根目录的
version.txt（即 version.txt），也不要改动测试仓库的cases/_version.txt——版本号由执行 PR 合并的人统一处理； - 如果你想让别人区分你修改过的 tidy 版本，请使用 CMake 选项
-DTIDY_RC_NUMBER=I123，它会在tidy -v输出中体现为5.7.16.I123。数字可以随意，但建议直接采用相关 Issue 的编号。在源码中的印证：该选项在 CMakeLists.txt 中通过add_definitions(-DRC_NUMBER="${TIDY_RC_NUMBER}")注入编译宏，确实会影响版本字符串的生成。
了解测试工具与测试集结构
regression_testing/README.md 补充了更完整的细节：test.rb是一个跨平台的 Ruby 脚本，用于替代旧的 Windows shell 与 Bash 测试脚本，可用bundle install安装依赖后直接运行：
| 命令 | 作用 |
|---|---|
./test.rb test | 测试所有测试集的所有用例 |
./test.rb only <setname> | 只测试指定测试集 |
./test.rb case <case_number> | 只测试单个用例 |
默认使用的 tidy 位于tidy-html5/build/cmake/tidy[.exe]，也可以通过可选参数指定其他构建版本。测试集结构遵循固定约定：cases/<setname>/存放 HTML 输入（命名格式case-basename@n<.html|.xml|.xhtml>，@n表示期望的退出码）与可选的case-basename.conf配置；<setname>-expects/存放期望输出；<setname>-results/存放实际结果，便于直接diff。
回归测试的定位
值得说明的是，回归测试主要用于代码改动，但文档也鼓励把它养成习惯。回归测试是 Tidy 项目质量控制的主要手段——任何曾经通过的用例都应当继续通过，除非在 PR 讨论中明确说明并得到认可，否则“回归”就是拒绝 PR 的充分理由；同时，修复 bug 或新增功能最好附带一个能演示该问题/功能的测试用例，这能让维护者快速理解改动的影响面。
第五步：构建与验证环境——在提交前把本地环境跑通
贡献文档要求能“从源码构建 tidy”（依赖 CMake）。仓库内 README/BUILD.md 给出了三个平台的标准构建命令：
macOS / Linux / Unix：
cd build/cmake cmake ../.. -DCMAKE_BUILD_TYPE=Release [-DCMAKE_INSTALL_PREFIX=/path/for/install] make [sudo] make installmacOS（多架构，同时支持 Intel 与 Apple Silicon）：
cd build/cmake cmake ../.. -DCMAKE_BUILD_TYPE=Release "-DCMAKE_OSX_ARCHITECTURES=x86_64;arm64" make [sudo] make installWindows：
cd build/cmake cmake ../.. -DCMAKE_BUILD_TYPE=Release [-DCMAKE_INSTALL_PREFIX=/path/for/install] cmake --build . --config Release cmake --build . --config Release --target INSTALL几个实用细节：Unix 下-DCMAKE_BUILD_TYPE=Release会追加-DNDEBUG，去掉代码中的调试assert；Windows 下默认安装到C:\Program Files\tidy，编译产物tidy.exe位于Release目录，可自行复制到PATH中的任意目录；如需禁止共享库，可加-DBUILD_SHARED_LIB:BOOL=OFF（该选项默认ON，但静态库始终会编译并与命令行工具链接）。构建完成后，用tidy -v确认版本号，就进入了可以安心改代码、跑测试的状态。
在 foo_openlyrics 中理解 LibTidy 的使用姿势
作为 HTML Tidy 的嵌入式用户，foo_openlyrics 的集成方式对理解“为什么贡献文档要求提供 API 示例代码”很有帮助。在 src/sources/lyric_source.cpp 中：
TidyDoc tidy_doc = tidyCreate(); tidySetErrorBuffer(tidy_doc, &tidy_error); tidyOptSetBool(tidy_doc, TidyXhtmlOut, yes); tidyOptSetBool(tidy_doc, TidyForceOutput, yes); tidyParseString(tidy_doc, html); tidyCleanAndRepair(tidy_doc); tidyRunDiagnostics(tidy_doc); tidySaveBuffer(tidy_doc, &tidy_output); if (tidyErrorCount(tidy_doc) != 0) { /* 记录诊断信息 */ } doc.load_buffer(tidy_output.bp, tidy_output.size); tidyBufFree(&tidy_output); tidyBufFree(&tidy_error); tidyRelease(tidy_doc);这段代码把抓取到的网页 HTML 清洗为 XHTML 后交给 pugixml 解析，从中可以看到 LibTidy 的核心调用链：tidyCreate创建文档句柄 →tidySetErrorBuffer捕获诊断信息 →tidyOptSetBool设置输出选项 →tidyParseString解析 →tidyCleanAndRepair清洗修复 →tidyRunDiagnostics运行诊断 →tidySaveBuffer取结果 → 最后用tidyBufFree/tidyRelease释放资源。源码注释还特别提醒：在 Windows 上 TidyHtml 默认会向 stderr 输出调试消息，除非编译时定义DISABLE_DEBUG_LOG——这正是“配置影响行为”的一个活例子。如果你要扩展 Tidy 的能力或修复解析边界情况，这种集成代码就是提交 API 类 Issue/PR 时的最佳参考模板。
结语：一次健康的贡献闭环
回顾整个贡献流程，可以提炼出一条清晰的闭环：先用结构化信息报告问题 → 判断是否适合自己动手 → 用干净的分支和规范提交写代码 → 用独立测试仓库验证不引入回归 → 以附带 Issue 编号的 PR 交付。文档在结尾写道：“毫无疑问，所有的帮助都值得感激，我们需要共同努力让 Tidy 变得更好。”这套流程不仅适用于 HTML Tidy 本身，对任何依赖 Tidy 做 HTML 处理的嵌入项目（如 foo_openlyrics 的歌词抓取清洗）同样具有借鉴价值——理解了上游的协作与质量规范，也就理解了为什么应该以“小而聚焦、测试兜底”的方式去贡献代码。
【免费下载链接】foo_openlyrics
An open-source lyric display panel for foobar2000
相关推荐
Devise贡献指南：从Issue到Pull Request
Devise贡献指南：从Issue到Pull Request 你是否曾想为Devise贡献代码却不知从何入手？作为Ruby on Rails生态中最受欢迎的身份
认证鉴权后端揭秘iPod Classic JS的点击轮实现：从触觉反馈到导航逻辑的技术原理
揭秘iPod Classic JS的点击轮实现：从触觉反馈到导航逻辑的技术原理 iPod Classic JS是一款基于React和Styled Compone
前端SocketRocket源码贡献指南：从Issue到Pull Request全流程
SocketRocket源码贡献指南：从Issue到Pull Request全流程 你是否曾想为WebSocket客户端库SocketRocket贡献代码，但不
网络通信
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
