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 能否进入合并通道的硬门槛不符合贡献检查清单或违反贡献指南的代码未经事先讨论的大规模重构——原文指出这类重构会持续拖延进度、打断其他人的工作对项目的害处大于好处未经同意使用他人/其他项目的代码或代码许可证与本项目不兼容你自己也不理解、无法解释的代码原文称之为 vibe coding引入大量复杂性但收益甚微的代码。三、许可架构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将翻译 JSONsrc/tagstudio/resources/translations/*.json标注为GPL-3.0-or-later第三、四组REUSE.toml#L34-L57为引入的第三方图标资产单独标注了MITBoxicons与Apache-2.0Material 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 的要求可以归纳为五条Commit message 遵循 Conventional Commitsv1.0.0。这样做的直接目的是便于自动生成发布 changelog。仓库中的 .git-blame-ignore-revs 文件本身就是一个实证其中记录的批量格式化提交如ci(ruff)!: update ruff linter config, refactor to comply正是典型的 Conventional Commits 前缀风格ci(...)、refactor(docs)等。消息清晰简洁如果一个 commit 做得太多要么拆分成更小的 commit要么在 commit 描述中补充更多细节。PR 标题与描述要充分清楚说明意图和变更内容UI 类变更欢迎提供截图、GIF 或视频。一个 PR 原则上只包含单一功能或单一修复。不要在 PR 处于 review 状态时 force push。原文的解释是force push 会让审阅者无法区分哪些改动已审过、哪些没有迫使审阅者重审全部代码造成大量无谓工作量。关于 PR 边界的实用判断技巧原文给了一句值得记住的自检问题如果我把这个 PR 拆开其中某一部分能否在其余部分合并之前先被项目采用能就说明拆得不够彻底。五、推送前的自动化工作流检查docs/contributing.md 指出推送代码后会触发若干自动化工作流对代码执行预定义的测试与风格检查文档强烈建议在本地先跑一遍这些检查避免在 PR 里来回返工。检查项共四类全部可在仓库中定位到实际配置检查项作用仓库中的落地位置Ruffcheckformatformat 只读检查Lint 与格式校验.pre-commit-config.yaml 中的ruff/ruff-format钩子配置见 pyproject.toml#L119-L125line-length 100启用B、D、E、F、I、SIM、UP等规则组Pyright 类型检查静态类型严格性pyproject.toml#L96-L101include覆盖src/tagstudio与tests并豁免src/tagstudio/previews/vendored/pydub/与遗留的src/tagstudio/core/library/json/Pytest 测试功能回归测试pyproject.toml#L88-L94qt_api pyside6、pythonpath [src]测试位于 tests/REUSE 许可合规逐文件许可证校验.github/workflows/reuse.yml基于fsfe/reuse-action本地对应 pre-commit 钩子中的reuse lint-filePython 相关的具体 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 与 11macOS 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 .venvpip 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.nixIDE 调试入口为 src/tagstudio/main.pycontrib/ 下提供编辑器参考配置。八、小结这份指南的实际约束链路把 docs/contributing.md 各节串起来TagStudio 对贡献者的约束形成一条完整链路动工前先开 issue功能必须→ 代码符合可理解、低复杂度、无多余日志的边界 → 文件带上正确 SPDX 头、归入 MITcore或 GPL-3.0Qt 前端的正确一侧 → commit message 用 Conventional Commits → PR 单一主题、review 期间不 force push → 本地 pre-commit 与 CI 四类检查全绿 → 在 Windows 10/11、macOS 14、常见 Linux 发行版上均无异常行为。这条链路的每一环都能在仓库中找到可验证的落点许可声明在 REUSE.toml 与各文件头检查配置在 .pre-commit-config.yaml 与 pyproject.tomlCI 定义在 .github/workflows/ 下的checks_python.yml与reuse.yml。【免费下载链接】TagStudioA User-Focused Photo File Management System项目地址: https://gitcode.com/GitHub_Trending/ta/TagStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 能否进入合并通道的硬门槛不符合贡献检查清单或违反贡献指南的代码未经事先讨论的大规模重构——原文指出这类重构会持续拖延进度、打断其他人的工作对项目的害处大于好处未经同意使用他人/其他项目的代码或代码许可证与本项目不兼容你自己也不理解、无法解释的代码原文称之为 vibe coding引入大量复杂性但收益甚微的代码。三、许可架构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将翻译 JSONsrc/tagstudio/resources/translations/*.json标注为GPL-3.0-or-later第三、四组REUSE.toml#L34-L57为引入的第三方图标资产单独标注了MITBoxicons与Apache-2.0Material 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 的要求可以归纳为五条Commit message 遵循 Conventional Commitsv1.0.0。这样做的直接目的是便于自动生成发布 changelog。仓库中的 .git-blame-ignore-revs 文件本身就是一个实证其中记录的批量格式化提交如ci(ruff)!: update ruff linter config, refactor to comply正是典型的 Conventional Commits 前缀风格ci(...)、refactor(docs)等。消息清晰简洁如果一个 commit 做得太多要么拆分成更小的 commit要么在 commit 描述中补充更多细节。PR 标题与描述要充分清楚说明意图和变更内容UI 类变更欢迎提供截图、GIF 或视频。一个 PR 原则上只包含单一功能或单一修复。不要在 PR 处于 review 状态时 force push。原文的解释是force push 会让审阅者无法区分哪些改动已审过、哪些没有迫使审阅者重审全部代码造成大量无谓工作量。关于 PR 边界的实用判断技巧原文给了一句值得记住的自检问题如果我把这个 PR 拆开其中某一部分能否在其余部分合并之前先被项目采用能就说明拆得不够彻底。五、推送前的自动化工作流检查docs/contributing.md 指出推送代码后会触发若干自动化工作流对代码执行预定义的测试与风格检查文档强烈建议在本地先跑一遍这些检查避免在 PR 里来回返工。检查项共四类全部可在仓库中定位到实际配置检查项作用仓库中的落地位置Ruffcheckformatformat 只读检查Lint 与格式校验.pre-commit-config.yaml 中的ruff/ruff-format钩子配置见 pyproject.toml#L119-L125line-length 100启用B、D、E、F、I、SIM、UP等规则组Pyright 类型检查静态类型严格性pyproject.toml#L96-L101include覆盖src/tagstudio与tests并豁免src/tagstudio/previews/vendored/pydub/与遗留的src/tagstudio/core/library/json/Pytest 测试功能回归测试pyproject.toml#L88-L94qt_api pyside6、pythonpath [src]测试位于 tests/REUSE 许可合规逐文件许可证校验.github/workflows/reuse.yml基于fsfe/reuse-action本地对应 pre-commit 钩子中的reuse lint-filePython 相关的具体 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 与 11macOS 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 .venvpip 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.nixIDE 调试入口为 src/tagstudio/main.pycontrib/ 下提供编辑器参考配置。八、小结这份指南的实际约束链路把 docs/contributing.md 各节串起来TagStudio 对贡献者的约束形成一条完整链路动工前先开 issue功能必须→ 代码符合可理解、低复杂度、无多余日志的边界 → 文件带上正确 SPDX 头、归入 MITcore或 GPL-3.0Qt 前端的正确一侧 → commit message 用 Conventional Commits → PR 单一主题、review 期间不 force push → 本地 pre-commit 与 CI 四类检查全绿 → 在 Windows 10/11、macOS 14、常见 Linux 发行版上均无异常行为。这条链路的每一环都能在仓库中找到可验证的落点许可声明在 REUSE.toml 与各文件头检查配置在 .pre-commit-config.yaml 与 pyproject.tomlCI 定义在 .github/workflows/ 下的checks_python.yml与reuse.yml。【免费下载链接】TagStudioA User-Focused Photo File Management System项目地址: https://gitcode.com/GitHub_Trending/ta/TagStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考