OHIF 开发流程：Issue 分类、PR 评审、质量保障与自动发布机制

OHIF 开发流程：Issue 分类、PR 评审、质量保障与自动发布机制

【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers

本指南以 OHIF Viewer 官方文档 Our Process 为骨架，系统讲解 OHIF 开源协作背后的完整工作流：社区 Issue 如何被分类、筛选并转化为可执行的后台任务；Pull Request 从提交到合入master需要经过哪些标签、评审与质量关卡；以及 CI、自动化测试与发布管线如何支撑"代码合入即自动发布"的工程体系。读完本文，你将掌握参与 OHIF 社区贡献的完整路径，理解每个标签的含义，并能据此判断一个 Issue 或 PR 处于流程的哪个阶段、下一步会走向哪里。

总览：一套"活"的协作流程

OHIF 团队的开发流程并不是一成不变的僵化制度，而是一套"有生命的、不断演进"的流程（living, breathing thing）。团队通过定期召开 retrospective（回顾会议） 来审视和调整流程，使其始终匹配团队当下的需求。官方文档将其目的概括为两点：

• 增强社区成员的参与度和理解力；
• 欢迎反馈与有益的建议。

这一流程贯穿 OHIF Viewer 的整个生命周期，从用户提交 Issue 开始，到社区讨论、后台积压（backlog）管理、PR 评审、质量保障（QA），最终落到自动化的发布与部署。仓库的顶层文档 CONTRIBUTING.md 将贡献者引导至 开发文档 与 Getting Started，而本文所讲的流程正是这套贡献体系的核心运行机制。

Issue 分类（Issue Triage）：三类社区模板

GitHub Issues 是社区向 OHIF Viewer 核心团队反馈问题、提问和提出变更建议的最佳渠道。社区提交的 Issue 通常分为三类，创建时会自动打上triage标签（需要分诊处理）。

表 1. Issue 模板名称与描述

上述模板在当前仓库中有对应的 YAML 配置，例如 bug-report.yml 定义了 Bug 报告的必填字段（Bug 描述、复现步骤、当前行为、预期行为），并要求提交者运行npx envinfo --system --binaries --browsers粘贴系统信息，同时提醒"无法复现的报告有被标记为 stale 并关闭的风险"；feature-request.yml 则要求说明"希望看到什么功能/变更"以及"为什么应该优先处理该功能"。config.yml进一步配置了模板选择页的行为。这些结构化模板从源头保证了 Issue 的信息质量，是后续高效分诊的基础。

分诊承诺与节奏

需要triage的 Issue 类似于"支持工单"。由于这通常是团队与潜在采用者、贡献者的首次接触，及时响应与满意解决至关重要。官方流程对此做出了明确承诺：

1. 每周至少响应一次需要triage的 Issue；
2. 从"社区 Issue"中提炼出新的"官方 Issue"；
3. 在适用时提供清晰的指引与后续步骤；
4. 定期清理过时（stale）的 Issue。

值得注意的是，Issue 中反映出的模式往往能揭示需要改进的领域。文档中给出的例子是：用户在使用 OHIF Viewer 时经常遇到 CORS（跨域资源共享）配置问题——通过观察这类重复出现的工单，团队可以思考如何从产品层面降低该问题的工单量。仓库中关于 CORS 部署的更多细节可参考 部署文档。

后台积压（Backlog）：从讨论到可执行任务

社区 Issue 是讨论的载体，最终会引导出"后台积压 Issue"（backlogged issues）。后台积压 Issue 是从社区 Issue 中提炼出的、精炼且可执行的信息，包含移交核心团队（或社区）贡献者所需的范围（scope）与需求（requirements）。积压的 Issue 分为三类，每类对应固定的标签：

表 2. 后台积压 Issue 类型与对应标签

积压管理与"Active Development"看板

如果一个 GitHub Issue 带有bug、story或task标签，它就进入了 backlog。进入 backlog 意味着团队至少承诺会认真审查任何社区提交的、用于完成该 Issue 的 Pull Request。如果你希望某个 Issue 被完成但不知从何下手，可以直接在该 Issue 下留言询问。

虽然项目暂时没有长期或季度路线图，但团队会定期将条目添加到 "Active Development" GitHub Project Board。看板上的条目要么正由核心团队成员积极开发，要么在现有工作完成后排队进入开发。仓库中的 Architecture 文档 描述了 monorepo 中平台包、扩展包与模式（modes）的划分方式，可作为理解 backlog 中任务归属的参考。

想贡献但不知从何开始？可以关注标有 "Up for grabs" 的 Issue，并阅读 Contributing 文档。

贡献与 PR 评审（Contributions & Pull Requests）

PR 的三组标签体系

进入的 Pull Request 使用以下标签进行分诊。所有被判定为合适的 Bug 修复或功能添加的 PR 都会经过代码评审（code review）：

表 3. PR 分诊标签

合入master的硬性门槛

团队依赖 GitHub Checks 和第三方服务的集成来评估代码质量与测试覆盖率的变化。在 PR 合入master之前，必须满足：

• 所有测试必须通过；
• 用户场景描述（user cases）在适用时必须在 PR 中给出；
• 代码质量和测试覆盖率不得出现显著下滑（must not be changed by a significant margin）；
• 部分仓库还包含基于视觉截图的测试，端到端测试的视频录像会被保存以供后续复查。

此外，pull_request_template.md 要求作者在提交前勾选一系列检查项，包括：PR 标题必须遵循 semantic-release 格式（如feat(MeasurementService): add ...、fix(Toolbar): fix ...，因为 squashed 后的 PR 标题将作为 commit message）；代码需要有良好的文档注释；公共 API 变更需要同步更新文档；并注明测试环境（OS、Node 版本、浏览器）。

CI 流水线：每个 PR 都要过一遍的质量关卡

文档强调"可以在这里关于持续集成的内容"，对应文件为 continuous-integration.md。OHIF 仓库使用CircleCI和Netlify构建 CI/CD 体系：

• Netlify Deploy Previews：每个 PR 都会生成部署预览，让作者和评审者像"合并后"一样预览 OHIF Viewer 的效果。可通过根目录 netlify.toml 配置，额外的脚本/资源位于根目录.netlify目录。
• CircleCI Workflows：工作流的定义在.circleci/config.yml中，包括以下核心工作流：
  • PR_CHECKS：每次代码提交都会运行单元测试与端到端测试，全部通过才能合入master。从当前仓库配置看，该工作流包含BUILD_PACKAGES_QUICK、UNIT_TESTS与 Cypress 端到端测试三个并行/顺序作业；
  • PR_OPTIONAL_DOCKER_PUBLISH：允许通过"手动审批"将 PR 发布为带标签的 Docker 镜像，便于在合入前与 Google Adapter 联调。注意：该工作流只对upstream仓库的分支生效，来自 fork 的分支需要先合入 upstream 上短期的feature/分支；
  • DEPLOY：变更合入master后部署 OHIF Viewer，使用 Netlify CLI 部署 PWA 构建产物（pnpm run build），并通过"手动审批"晋升到 STAGING 与 PRODUCTION 环境；
  • RELEASE：合入master后发布 npm 包、更新文档并构建 Docker 镜像。使用 Lerna 与 Semantic Commit 语法对 monorepo 中的多个包独立版本化与发布；发布新版本时会创建 Docker 镜像，文档通过 gitbook 生成并推送至gh-pages分支，由 GitHub Pages 托管。

三个运行环境：Dev / Staging / Prod

PWA 版本（Progressive Web Application）的 OHIF Viewer 部署在开发、预发与生产三个环境中：

表 4. 三套运行环境

发布流程（Releases）：语义化版本与自动发布

OHIF 的发布机制高度自动化，核心规则如下：

• 版本号自动决定：根据已合入提交的类型（major.minor.patch）自动决定版本升级；
• 自动推送 NPM：新版本自动发布到 NPM；
• 自动生成发布说明：release notes 自动生成；
• 多渠道订阅：用户可订阅 GitHub 与 NPM 的发布通知。

重要公告会在 GitHub 上发布、标记为 Announcement 并置顶，使其始终停留在 Issue 页面顶部。

核心团队还会定期执行完整的手动测试，以启动 Stable 版本的发布流程。测试完成后，已知问题被解决，随后发布 Stable 版本。从当前仓库的 CircleCI 配置（.circleci/config.yml）可以印证这套发布机制：DEPLOY_MASTER工作流（对应 viewer-dev.ohif.org）在 BUILD 之后依次执行NPM_PUBLISH、DOCKER_BETA_PUBLISH、ARM 构建与多架构 manifest 合并；DEPLOY_RELEASE工作流（对应 viewer.ohif.org）在 BUILD 之后设有HOLD_FOR_APPROVAL手动审批节点，随后才执行 NPM 发布与 Docker release 发布。仓库根目录的 package.json 中可以看到pnpm作为包管理器（packageManager: pnpm@11.5.2，Node >= 24）以及cm（npx git-cz）等与提交规范相关的脚本，这与 PR 模板中要求的 semantic-release 提交格式一脉相承。

仓库中的自动化辅助设施

除上述流程外，当前仓库还内置了若干与流程配套的自动化配置，可以作为理解整套机制的一手材料：

• stale.yml：配置 GitHub Stale App。Issue 在 180 天无活动后会被标记为 stale（标记为Stale 🥖），再过 60 天无活动则被关闭；Bug: Verified 🐛、PR: Awaiting Review 👀、Announcement 🎉、Community: Request/Report等标签被豁免。这对应了分诊流程中"定期清理过时（stale）Issue"的承诺，也解释了 Bug 模板中"无法复现的报告可能被标记为 stale 并关闭"的警告。
• playwright.yml：GitHub Actions 上的 Playwright 端到端测试工作流，针对 PR 在master与release/*分支运行，包含 CS3D（cornerstone3D）集成测试逻辑，可将测试结果与覆盖率报告上传为 Artifacts。仓库根目录的 package.json 提供了test:e2e、test:e2e:coverage、test:e2e:ui等本地运行脚本，相关编写指南见 playwright-testing.md。
• codeql.yml与FUNDING.yml：前者用于安全代码扫描，后者配置项目赞助入口。

结语：从 Issue 到发布的一次完整旅程

回顾整个流程，一次典型的社区贡献会经历以下阶段：

1. 提交 Issue：通过三套社区模板之一提交，被打上triage标签，进入每周分诊；
2. 沉淀为 backlog：讨论成熟后提炼为带Bug/Story/Task标签的积压任务，加入 Active Development 看板排队；
3. 提交 PR：贡献者提交 PR，经过分类、评审、QA 三组标签的状态流转，通过所有 GitHub Checks（单元测试、E2E、代码质量、覆盖率）后合入master；
4. 自动发布：CI 依据提交类型自动确定版本号，发布 npm 包、Docker 镜像与文档，并经 Dev → Staging → Production 逐步部署。

这套流程的价值在于：它把开源社区常见的"混乱讨论"通过分类、标签、自动化检查与发布管线，转化为可追踪、可协作、可自动交付的工程体系。无论你是想提交 Bug、请求功能、贡献代码还是只是提问，理解这套流程都能让你的参与更高效，也更容易被核心团队采纳。

【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers