TagStudio 贡献工作流与许可架构：从 REUSE 逐文件授权到 CI 自动化检查

TagStudio 贡献工作流与许可架构：从 REUSE 逐文件授权到 CI 自动化检查

【免费下载链接】TagStudioA User-Focused Photo & File Management System项目地址: https://gitcode.com/GitHub_Trending/ta/TagStudio

本文以 docs/contributing.md 为骨架，完整解析 TagStudio 项目的贡献流程：提交前检查清单、不可接受的代码边界、"MIT 核心 + GPL-3.0 Qt 前端"的双轨许可证架构（基于 REUSE 规范与 SPDX 头实现逐文件授权），以及 Conventional Commits、PR 规范、CI 自动化检查（Ruff / Pyright / Pytest / REUSE）和跨平台运行时要求。读完本文，你将掌握向该项目提交代码的完整合规路径，并能在REUSE.toml、.pre-commit-config.yaml与 pyproject.toml 中验证每一条规则的实际落地方式。

一、提交前的贡献检查清单

docs/contributing.md 将贡献流程分为三类检查项，覆盖了"所有贡献 / 功能新增 / 缺陷修复"三种场景：

所有贡献（通用项）

• 阅读贡献指南（即该文档）与风格指南；
• 阅读项目 README 中的 FAQ（参见 README.md）；
• 在开始工作前检查项目已有的 Pull Request，避免与现存或冲突的 PR 重复；
• 按 开发环境指南 搭建好开发环境，包括Ruff、Pyright与Pytest三套本地工具链。

功能新增

• 阅读路线图，了解已规划的核心功能、优先级与时间表；
• 在开始开发之前，先找到已有的 feature request 或自己新建一个 issue，让功能方案在动工前被讨论、批准或否决。原文档特别强调（danger 级别警示）：维护方不希望出现"因为功能与项目目标、指南或已规划功能冲突而不得不关闭 PR"的情况，所以"先开 issue、后写代码"是硬性要求。

缺陷修复

• 若修复足够重要（"substantial enough"），应先找到或新建对应的 bug report。
• 小修复豁免：如果修复很小且不言自明（例如错别字），则无需先开 issue——原文档的注记说明，issue 跟踪机制"应该让大家的处境更容易，而不是更难"，请自行判断以最小化所有人的工作量。

二、不可接受的代码边界

docs/contributing.md 明确列出了不会被接受的代码类型，这是 PR 能否进入合并通道的硬门槛：

1. 不符合贡献检查清单或违反贡献指南的代码；
2. 未经事先讨论的大规模重构——原文指出这类重构会"持续拖延进度、打断其他人的工作"，对项目的害处大于好处；
3. 未经同意使用他人/其他项目的代码，或代码许可证与本项目不兼容；
4. 你自己也不理解、无法解释的代码（原文称之为 "vibe coding"）；
5. 引入大量复杂性但收益甚微的代码。

三、许可架构：MIT 核心 + GPL-3.0 Qt 前端

这是本文档最具技术实质的一节。根据 docs/contributing.md，自 2026 年 5 月起，TagStudio 开始将代码库中不同部分迁移到不同许可证：位于 TagStudio "core" 内部的新贡献代码必须采用 MIT 许可，而专属于 Qt 前端的代码在可行范围内保持 GPL-3.0。

3.1 REUSE 规范与逐文件授权

许可管理采用REUSE 规范（原文引用 REUSE spec 3.3）实现。其核心机制是：每个文件单独持有许可证——文本文件在文件头写注释声明版权与许可证，非文本文件（图片、模板等）则在 REUSE.toml 中统一声明。当前仓库的 REUSE.toml 正是这一机制的落地证据：

• 第一组注解（REUSE.toml#L3-L27）将测试夹具（tests/fixtures/**）、文档资源（docs/assets/**）、Qt 图片资源（src/tagstudio/resources/qt/images/**）、.gitignore、flake.lock等文件统一标注为GPL-3.0-only；
• 第二组（REUSE.toml#L29-L32）将翻译 JSON（src/tagstudio/resources/translations/*.json）标注为GPL-3.0-or-later；
• 第三、四组（REUSE.toml#L34-L57）为引入的第三方图标资产单独标注了MIT（Boxicons）与Apache-2.0（Material Design Icons）及各自版权归属——这正是"逐文件授权"允许混入不同许可资产的体现。

对应的许可证全文文本存放在 LICENSES/ 目录，包含MIT.txt、GPL-3.0-only.txt、GPL-3.0-or-later.txt、Apache-2.0.txt、CC0-1.0.txt等，与 SPDX 标识符一一对应。

3.2 SPDX 文件头写法

原文档给出了四种文件类型的标准 SPDX 头（完整继承自 docs/contributing.md#L64-L87），新增代码时必须照此写入：

# SPDX-FileCopyrightText: (c) TagStudio Contributors # SPDX-License-Identifier: GPL-3.0-only

# SPDX-FileCopyrightText: (c) TagStudio Contributors # SPDX-License-Identifier: MIT

<!-- SPDX-FileCopyrightText: (c) TagStudio Contributors --> <!-- SPDX-License-Identifier: GPL-3.0-only -->

/* * SPDX-FileCopyrightText: (c) TagStudio Contributors * SPDX-License-Identifier: GPL-3.0-only */

仓库内任意文本文件（如 docs/contributing.md 自身的头两行注释）都遵循这一格式，可作为直接参照。

3.3 哪些文件应归 MIT，哪些归 GPL-3.0

原文档的划分标准（docs/contributing.md#L89-L100）与仓库实际目录结构高度吻合：

应归 MIT 的文件类型：

• 支撑 TagStudio 核心系统、不依赖具体前端的后端代码——例如数据库后端、搜索查询系统、数据库测试等。从源码结构看，对应src/tagstudio/core/下的 library/（SQLite 库与注册表）、query_lang/（搜索查询解析器）等模块；
• CLI 前端的代码（原文标注 "to be developed"，即尚未开发）；
• 平台无关的缩略图提取、渲染与缓存代码——从源码结构看，对应 src/tagstudio/previews/renderers/ 中各渲染器；
• 添加到 MIT 标签 Weblate 组件中的翻译。

应归 GPL-3.0 的文件类型：

• Qt 前端代码——即 Qt 控件、视图、控制器、Qt 渲染代码、Qt 测试等，对应 src/tagstudio/qt/ 下的controllers/、views/、mixed/等模块。

重新授权（Relicensing）规则：已有的 GPL-3.0 核心代码只有在所有原始贡献者均表示同意、或该代码被"显著不同的新实现"替换时，才迁移到 MIT。这保证了 MIT 化过程不侵犯既有贡献者的权利。

四、Commit 与 Pull Request 规范

docs/contributing.md 对提交与 PR 的要求可以归纳为五条：

1. Commit message 遵循 Conventional Commits（v1.0.0）。这样做的直接目的是便于自动生成发布 changelog。仓库中的 .git-blame-ignore-revs 文件本身就是一个实证：其中记录的批量格式化提交（如ci(ruff)!: update ruff linter config, refactor to comply）正是典型的 Conventional Commits 前缀风格（ci(...)、refactor(docs)等）。
2. 消息清晰简洁：如果一个 commit 做得太多，要么拆分成更小的 commit，要么在 commit 描述中补充更多细节。
3. PR 标题与描述要充分，清楚说明意图和变更内容；UI 类变更欢迎提供截图、GIF 或视频。
4. 一个 PR 原则上只包含单一功能或单一修复。
5. 不要在 PR 处于 review 状态时 force push。原文的解释是：force push 会让审阅者无法区分哪些改动已审过、哪些没有，迫使审阅者重审全部代码，造成大量无谓工作量。

关于 PR 边界的实用判断技巧，原文给了一句值得记住的自检问题："如果我把这个 PR 拆开，其中某一部分能否在其余部分合并之前先被项目采用？"能，就说明拆得不够彻底。

五、推送前的自动化工作流检查

docs/contributing.md 指出，推送代码后会触发若干自动化工作流，对代码执行预定义的测试与风格检查；文档"强烈建议"在本地先跑一遍这些检查，避免在 PR 里来回返工。检查项共四类，全部可在仓库中定位到实际配置：

Python 相关的具体 CI 定义在 .github/workflows/checks_python.yml，其中包含一个run-conditions作业，先根据变更文件动态决定是否需要运行 pyright / pytest / ruff。

本地复现 CI 的四条命令

按 docs/developing.md 的工具链章节，上述检查在本地等价于：

ruff check # Lint（自动修复：ruff check --fix） ruff format # 格式化 pyright # 类型检查 pytest tests/ # 运行测试

更进一步，仓库提供了 pre-commit 配置，pre-commit install后在每次git commit时自动执行reuse lint-file、pyright、ruff check --force-exclude与ruff format --force-exclude --check四个钩子——也就是说，本地提交流程与 CI 检查项是一一对应的，这正是原文"推送前先本地跑检查"建议的具体执行方式。

六、运行时要求

docs/contributing.md 规定代码必须在所有受支持的操作系统与版本上工作：

• Windows 10 与 11；
• macOS 14.0+；
• 常见的 Linux 发行版及版本。

最终提交的代码不允许做到以下任何一点：

• 包含多余的、不必要的日志语句；
• 在"有进度提示的任务"之外造成不合理的程序减速；
• 在屏幕上造成不期望的视觉故障或伪影。

这三条实质上是针对 TagStudio 作为桌面媒体管理工具的特性约束：缩略图渲染、预览加载等路径上的性能与视觉质量是硬性验收标准。

七、开发环境速查（检查清单第 4 项的落地）

贡献检查清单要求开发者先按 docs/developing.md 搭好环境，关键事实摘录如下（以当前仓库文档为准）：

• Python 3.14为开发要求版本（任意 3.14.x）；
• 依赖安装三选一：uv pip install -e . --group all（推荐）、poetry install --with dev，或手动python -m venv .venv+pip install -e . --group all；其中--group all对应的依赖组在 pyproject.toml#L48-L55 中聚合了check、build、docs、extra四个组，Ruff/Pyright/Pytest 均随之安装；
• Nix 用户可直接nix develop进入 flake 提供的开发环境（见 flake.nix、nix/shell.nix）；
• IDE 调试入口为 src/tagstudio/main.py，contrib/ 下提供编辑器参考配置。

八、小结：这份指南的实际约束链路

把 docs/contributing.md 各节串起来，TagStudio 对贡献者的约束形成一条完整链路：动工前先开 issue（功能必须）→ 代码符合"可理解、低复杂度、无多余日志"的边界 → 文件带上正确 SPDX 头、归入 MIT（core）或 GPL-3.0（Qt 前端）的正确一侧 → commit message 用 Conventional Commits → PR 单一主题、review 期间不 force push → 本地 pre-commit 与 CI 四类检查全绿 → 在 Windows 10/11、macOS 14+、常见 Linux 发行版上均无异常行为。这条链路的每一环都能在仓库中找到可验证的落点：许可声明在 REUSE.toml 与各文件头，检查配置在 .pre-commit-config.yaml 与 pyproject.toml，CI 定义在 .github/workflows/ 下的checks_python.yml与reuse.yml。

【免费下载链接】TagStudioA User-Focused Photo & File Management System项目地址: https://gitcode.com/GitHub_Trending/ta/TagStudio