Streamlit PR 规范速查：分支命名、提交信息、标签体系与测试计划完整指南

数据可视化后端前端【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址https://gitcode.com/gh_mirrors/st/streamlit点击查看免费下载本篇技术指南以 Streamlit 仓库的 wiki/pull-requests.md 为骨架系统梳理向 Streamlit 提交 Pull Request 时必须遵循的协作规范包括主分支约定、kebab-case 分支命名、命令式提交信息、PR 标题与描述写法、强制标签体系以及测试计划的填写要求。读完本文你将能按照 Streamlit 维护团队的标准一次性提交一份合规、可快速通过 CI 与评审的 PR并理解这些规范在仓库自动化工作流标签校验、changelog 归类、spec 校验中的真实落地方式。先读模板canonical PR templateStreamlit 仓库的 PR 规范以.github/pull_request_template.md为权威模板canonical PR templatewiki/pull-requests.md 只是它的快速参考quick reference。提交 PR 时GitHub 会自动以该模板预填充 PR 描述其结构为## Describe your changes ## GitHub Issue Link (if applicable) ## Testing Plan - Explanation of why no additional tests are needed - Unit Tests (JS and/or Python) - E2E Tests - Any manual testing needed? --- **Contribution License Agreement** By submitting this pull request you agree that all contributions to this project are made under the Apache 2.0 license.注意模板末尾的 Apache 2.0 贡献协议声明提交即视为同意以 Apache 2.0 许可贡献代码。这也是 CONTRIBUTING.md 中强调的Properly fill out the PR template with concrete details (not placeholders)——不要用占位符填充每个字段都要给出具体内容。主分支developStreamlit 仓库的主分支main branch是develop所有 PR 默认以develop为基线合并。这决定了分支创建的起点新功能分支应从最新的develop拉出PR 的目标分支也是develop。分支命名{type}/{brief-description}分支名必须遵循kebab-case全小写、连字符分隔格式为{type}/{brief-description}其中type只能是以下四类之一Type语义feature新功能fix缺陷修复refactor重构不改变外部行为chore维护性工作依赖升级、工具链等docs文档变更官方示例feature/add-height-parameter-plotly-charts fix/dataframe-memory-leak-large-datasets refactor/element-width-height-logic chore/update-react-dependencies命名要点描述性且具体3-8 个单词避免在分支名里带 ticket/issue 编号——编号请放进 PR 描述模板中的 GitHub Issue Link 字段而不是分支名。提交信息imperative verb what where提交信息遵循动词 做了什么 在哪里的格式规则如下首行 ≤ 50 字符使用命令式语气Add 而非 Added结尾不加句号可选正文每行 ≤ 72 字符。官方示例Add height parameter to plotly charts Fix memory leak in dataframe scrolling Refactor layout config validation logic命令式语气的意义在于让 Git 历史读起来像这条提交做了什么动作而非某时刻发生了什么便于日后按语义检索和生成 changelog。PR 标题[type] Description of changePR 标题格式为[type] Description of change长度≤ 63 字符——这个限制是为了适配 squash-merge 后生成的提交主题commit subject保证合入develop后的单条提交信息依旧整洁。标题的type使用方括号标签与分支 type 一一对应[feature]、[fix]、[refactor]、[chore]、[docs]。官方示例[feature] Add height parameter to plotly charts [fix] Extra padding on button [refactor] Layout config validation logic描述变更Highlight what matters. Omit the obvious.PR 描述的核心原则只有一句话突出关键变更省略显而易见的内容Highlight what matters. Omit the obvious.。写入 PR 描述前对每一条候选内容依次自问三个问题它是否从代码本身就能看出来测试、类型、校验、lint 规则已隐含的信息→ 省略它是不是影响最大的变更→ 写入它是否涉及不直观的决策→ 写入并给出解释PR 描述控制在2-4 条要点直接陈述变更内容不要写元评论meta-commentary即不要出现 This PR...、I added... 这类叙述性前缀。原文给出的 Good 示例Addsheightparameter tost.plotly_chart()usingHeighttype system.Addedheightparameter with defaultstretchDeprecatesuse_container_height(removed after 2025-12-31)Bad 示例逐条罗列显而易见的实现细节Addedheightparameter to signatureUpdated layout config dataclassAdded validation for height valuesAdded unit testsUpdated type hints为什么后者是 Bad因为改签名、改 dataclass、加校验、加测试、改类型标注全部属于第一条判断标准代码可自证的范围只有新增height参数和弃用use_container_height才是真正有影响力、非显而易见的信息。标签体系每个 PR 必贴两个标签所有 PR 都要求贴两个标签这是 Streamlit PR 流程的硬性门槛类别可选项Impact影响面impact:users影响用户行为或impact:internal仅内部影响Change type变更类型change:feature·change:bugfix·change:chore·change:refactor·change:docs·change:spec·change:other两个特殊说明change:spec豁免仅用于 spec/design 文档类 PR即specs/目录下的产品设计文档这类 PR 免贴impact:*标签凡是包含代码改动的 PR 一律不得使用change:spec。每个类别必须且只能选一个impact:*二选一change:*七选一。标签的自动化强制require-labels 工作流标签要求并非仅靠人工自觉而是由 CI 工作流 .github/workflows/require-labels.yml 强制执行的。该工作流在 PRopened / labeled / unlabeled / synchronize事件时触发通过actions/github-script读取 PR 当前标签并校验三条规则change-description必须恰好命中一个change:*标签缺失、重复选择都会报错impact-defined必须恰好命中一个impact:*标签do-not-merge禁止出现do-not-merge标签。校验逻辑还实现了change:spec的豁免分支当检测到change:spec标签时impact-defined检查会被跳过bypassedChecks new Set([impact-defined])与 wiki 文档的描述完全一致。任何一项不满足core.setFailed会让该检查失败并阻断合并。change:spec 的额外校验spec-validation 工作流针对change:spec标签的 PR还有专门的 .github/workflows/spec-validation.yml 工作流它只在改动specs/**且带change:spec标签的 PR 上运行逐个校验每个 spec 目录目录名必须符合YYYY-MM-DD-name格式且日期前缀必须是合法日期目录内必须存在product-spec.md或tech-spec.md文件 frontmatter 必须包含有效的author与createdYYYY-MM-DD字段。从仓库的 specs/ 目录可以看到这些规范的产物例如 2026-05-02-mermaid-chart/product-spec.md、2026-06-03-outside-container-writes/product-spec.md 等。也就是说change:spec不只是个标签它代表一条完整的产品设计文档提交流程。标签的下游价值changelog 自动归类标签体系不仅服务 CI 门槛还直接驱动发布流程。仓库脚本 scripts/changelog_categorize_prs.py 的categorize_prs函数按标签优先级对 PR 分类change:breaking→ breaking changes脚本支持该标签尽管它不在 PR 可选标签表中change:feature→ featureschange:bugfix→ bugfixes其余带impact:users或任意change:*→ other changes无标签 → unlabeled需要人工复查。同时仅带impact:internal而没有impact:users的 PR 会被排除出 changelogexclude_reason: internal-only因为内部重构、依赖升级等不改变用户可见行为的改动不该出现在面向用户的发布说明里。这与 wiki/release-process.md 中合并时添加change:chore和impact:users标签的实践一致。由此可见正确选择impact:usersvsimpact:internal直接决定了该 PR 是否会出现在 Streamlit 的公开 changelog 中。测试计划明确列出测试文件与其覆盖点测试代码的存放位置Streamlit 将测试按三层划分每种测试类型都有固定的存放模式测试类型存放模式典型示例Python 单元测试lib/tests/**/*.pylib/tests/streamlit/elements/plotly_chart_test.py前端单元测试frontend/**/*.test.ts或*.test.tsxfrontend/lib/src/components/core/Block/Block.test.tsxE2E 测试e2e_playwright/**/*_test.pye2e_playwright/st_plotly_chart_test.py从仓库结构可以验证这套划分lib/tests/streamlit/下是按模块组织的 389 个 Python 测试文件frontend/lib/src下是*.test.ts(x)单元测试e2e_playwright/下则是与st_*命令一一对应的 Playwright 测试文件如 e2e_playwright/st_plotly_chart_test.py 中的视觉回归测试test_plotly_has_consistent_visuals通过assert_snapshot对不同主题下的图表做截图比对。填写 PR 模板的 Testing Plan 清单根据哪些测试文件发生了变更来勾选 PR 模板中的 checklist如果改了 Python 代码 → 更新/新增lib/tests/**下的单元测试如果改了前端代码 → 更新/新增frontend/**下的.test.ts(x)单元测试如果涉及 UI 行为 → 更新/新增e2e_playwright/**下的 E2E 测试如果没有新增测试必须说明原因例如Documentation-only changes, no behavior modifications文档变更、无行为改动。然后在 PR 描述中以列出测试文件 覆盖点的方式描述测试计划原文示例- lib/tests/streamlit/elements/plotly_chart_test.py — Tests height parameter - e2e_playwright/st_plotly_chart_test.py — Visual regression tests for height这一写法与模板中 Testing Plan 的四个勾选项为何无需额外测试 / JS 与 Python 单元测试 / E2E 测试 / 是否需要手动测试一一对应评审者可以凭此快速判断测试覆盖是否充分。配套机制让 PR 通过评审的其余约定除了 wiki 文档本身仓库还有几条与之配套的 PR 协作约定PR 范围与响应时效CONTRIBUTING.md保持 PR 窄范围narrowly scoped改动过大应拆分为多个可独立评审的 PR先解决上一轮评审反馈再开启新一轮评审对 requested changes 或维护者提问应在 14 天内响应否则可能被降级处理反复提交低质量或不回应的 PR维护者可能暂停评审甚至关闭。AI 辅助贡献的归属CONTRIBUTING.md仓库欢迎负责任的 AI 辅助工具使用但 AI 不替代作者责任——提交 PR 的人需对变更的正确性、范围、可测试性和可维护性负责。仓库为此内置了一系列 PR 相关技能skills例如creating-pull-requests以正确标签和格式提交 PR、reviewing-pr-description评审 PR 标题与描述的清晰度、finalizing-pr合并前跑质量检查等详见 CONTRIBUTING.md。CI 全绿是合并前提.github/workflows/AGENTS.mdPR 需要通过的自动化检查包括python-tests.ymlPython 单元测试、lint、类型检查、js-tests.yml前端 TS lint、类型检查、Knip 未使用导出/依赖分析、Vitest 覆盖率、playwright.ymlwebkit / chromium / firefox 三浏览器的完整 E2E 套件、playwright-changed-files.yml仅跑改动测试文件的快速 E2E、enforce-pre-commit.yml全部 pre-commit 钩子与require-labels.yml标签校验等。提交 PR 前建议先跑本地make python-tests、make frontend-tests等命令自检。一张图记住全部约定把本文的规范浓缩为提交 PR 时的自查清单分支从develop拉出命名{type}/{kebab-case 描述}3-8 词不带 issue 号提交命令式动词 what where首行 ≤ 50 字符标题[type] Description≤ 63 字符适配 squash-merge描述2-4 条要点只写关键变更与非显而易见决策不写元评论标签impact:users/impact:internal二选一 change:*七选一纯 spec 文档 PR 用change:spec并豁免 impact测试计划按lib/tests/**、frontend/**/*.test.ts(x)、e2e_playwright/**/*_test.py三层列出改动文件及覆盖点无测试改动必须说明理由。遵循这套规范提交的 PR既能被require-labels.yml等 CI 检查自动放行也能让 changelog 脚本准确归类你的贡献还能显著降低评审往返成本——这正是 Streamlit 仓库在日均大量 PR 场景下维持高质量合入节奏的工程化保障。赞分享数据可视化后端前端【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址https://gitcode.com/gh_mirrors/st/streamlit点击查看免费下载相关推荐Elementor 的 Git 工作流规范详解分支命名、提交信息与 PR 指南Elementor 的 Git 工作流规范详解分支命名、提交信息与 PR 指南 本文基于 Elementor 仓库中的 Git 协作规则文档 .cursor/CMS前端后端低代码Git协作规范终极指南掌握分支命名与提交信息的10个核心技巧 Git协作规范终极指南掌握分支命名与提交信息的10个核心技巧 hello git项目是一个专门为初学者设计的Git和GitHub学习课程通过这个项目教程文档7个实用SSH工具让远程管理效率提升300%GitHub加速计划推荐7个实用SSH工具让远程管理效率提升300%GitHub加速计划推荐 GitHub加速计划的ss/ssh tools项目是一套让SSH使用更便捷的实用工具集上一篇RPSlidingMenu 开源项目教程下一篇如何参与awesome-golang-algorithm项目算法爱好者贡献指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考