开发工具代码编辑器数据科学【免费下载链接】positronPositron, a next-generation data science IDE项目地址https://gitcode.com/gh_mirrors/po/positron点击查看免费下载导读本文基于 Positron 仓库的 PR Body 模板参考 文档系统梳理 Positron 项目中 PR 描述PR Body的标准结构、六类 PR 类型模板、Release Notes 写法规范与 Validation Steps 最佳实践。同时结合仓库内的 PR Helper Skill、e2e 测试标签定义 与 CI 标签解析脚本深入讲解:测试标签的真实触发机制与安全书写规则。读完本文你将能写出符合 Positron 社区规范、能正确驱动 CI 测试的规范化 PR 描述。一、PR Body 模板总览组件与结构PR 描述是 Positron 仓库中每一次代码变更的“门面”它既要让评审者快速理解改动意图也要让 CI 系统从中解析出需要执行的 e2e 测试套件。模板参考文档将 PR Body 拆解为两个核心组件1.1 开头行Opening Line模式有关联 Issue 时使用 GitHub 的关闭关键词Fixes、Closes、Resolves使 PR 合并时 Issue 自动关闭Fixes #[issue_number]无关联 Issue 时直接写一句简要陈述说明 PR 做了什么[Brief statement of what the PR does].多个 Issue 时每个 Issue 都必须自带关闭关键词GitHub 才能逐个关联并关闭Fixes #[issue1], fixes #[issue2], and fixes #[issue3]1.2 描述Description模式简单描述2-3 句This PR [what it does]. The [root cause/reason]. [Any important implementation detail].复杂描述带标题与关联 PR### Summary [Paragraph explaining the changes] [Technical context paragraph if needed] Related PRs: - posit-dev/ark#[number] - [description] - posit-dev/positron-python#[number] - [description]Positron 是数据科学 IDE其内核ark、Python 语言支持positron-python等位于独立仓库因此跨仓库 PR 联动Paired PRs在描述中很常见SKILL.md 的 Step 1 也专门要求收集“Related PRs例如在 ark 仓库中”信息。二、六类 PR 类型模板完整参考与逐项解析模板参考文档按 PR 类型给出了六个可直接套用的模板。以下是完整继承并补充注释的版本。2.1 Bug Fix缺陷修复Fixes #[issue] This PR fixes [the problem]. The issue was caused by [root cause]. [Implementation approach if non-obvious]. ### Release Notes #### New Features - N/A #### Bug Fixes - [User-facing description of fix] (#[issue]) ### Validation Steps [relevant tags] [Simple reproduction steps and verification]要点Bug Fix 描述应点明“问题是什么、根因是什么、实现方式是否常规”。Release Notes 中的 Bug Fixes 条目必须写用户视角的描述并带上 Issue 编号。SKILL.md 中的示例Fix Data Explorer 滚动条在 Safari 上弹回 0正是这一模板的标准演绎。2.2 New Feature新功能Fixes #[issue] ### Summary This PR adds [feature description]. Users can now [what they can do]. [Technical implementation paragraph] [Related PRs if any] ### Release Notes #### New Features - [User-facing feature description] (#[issue]) #### Bug Fixes - N/A ### Validation Steps [relevant tags] [Numbered steps for testing]: 1. [Setup step] 2. [Action step] 3. [Verification step] [language] [Code example if helpful]要点新功能 PR 的 Validation Steps 建议使用**编号步骤**设置 → 操作 → 验证必要时附可运行的代码示例。SKILL.md 的 Example 2原生 DuckDB 连接支持展示了带 Python 代码示例的完整写法。 ### 2.3 UI/UX Change界面变更 markdown Fixes #[issue] This PR [describes the UI change]. The change improves [what it improves]. [Screenshot: Description of what the screenshot shows] ### Release Notes #### New Features - [User-visible UI change] (#[issue]) #### Bug Fixes - N/A ### Validation Steps [relevant tags including UI-specific ones] 1. [Navigate to the UI element] 2. [Perform the action] 3. [Verify the new behavior]要点UI 变更是唯一明确要求配截图的类型截图后应紧跟一句说明截图内容的文字。验证步骤按“定位 UI 元素 → 执行操作 → 验证新行为”三段式组织标签需包含 UI 相关套件如:editor-action-bar、:top-action-bar、:layouts等。2.4 Performance Improvement性能优化Fixes #[issue] ### Summary This PR optimizes [what was optimized]. Performance improves by [metrics/percentage] for [use case]. **Before:** [performance characteristic] **After:** [improved characteristic] ### Release Notes #### New Features - N/A #### Bug Fixes - N/A #### Performance - [User-facing performance improvement] (#[issue]) ### Validation Steps :performance [other relevant tags] [Steps to verify performance improvement]要点性能优化模板独特之处在于Release Notes 有独立的#### Performance小节要求在Before / After中给出可度量的性能特征指标或百分比Validation Steps 首行使用:performance标签——它在 FeatureTags 枚举 中是独立的功能标签会触发性能测试套件。2.5 Maintenance/Refactoring维护与重构[Brief description of maintenance work]. ### Summary This PR [refactoring description]. No user-facing changes. [Technical justification] ### Release Notes #### New Features - N/A #### Bug Fixes - N/A ### Validation Steps [relevant tags] Verify existing functionality still works: 1. [Test area 1] 2. [Test area 2]要点维护型 PR 明确声明“No user-facing changes”Release Notes 全部为 N/A验证重点转为回归验证——确认既有功能不受影响。2.6 E2E Test Additione2e 测试新增Adds e2e tests for [feature/area]. This PR adds comprehensive test coverage for [whats being tested]. The tests verify [key behaviors]. ### Validation Steps [tags for the areas being tested] Run the new tests: bash npx playwright test [test-file-name] --project e2e-electron要点测试类 PR 关注“覆盖了什么、验证了什么行为”并提供可复现的测试运行命令。仓库 e2e 测试基于 Playwright项目根目录的 [playwright.config.ts](https://link.gitcode.com/i/8ff4dcff186662d0f37ee6253973fd46) 定义了测试项目配置。 ## 三、Release Notes 撰写规范好例子与坏例子 模板参考文档给出了明确的判别标准核心原则是**面向用户、避免实现细节**。 **Features 好例子** - ✅ Added support for Python 3.12 virtual environments - ✅ Jupyter notebooks now support collapsible cell outputs - ✅ New keyboard shortcut kbdCmdShiftP/kbd opens command palette **Bug Fixes 好例子** - ✅ Fixed Data Explorer scrolling on Safari - ✅ Resolved console output truncation for long lines - ✅ Connections pane now correctly displays schema names with spaces **Too Technical过于技术化❌** - ❌ Refactored AbstractKernelManager to use dependency injection - ❌ Fixed race condition in async state machine **Too Vague过于含糊❌** - ❌ Improved performance - ❌ Fixed various bugs - ❌ Updated UI 判别逻辑很清晰AbstractKernelManager、dependency injection 这类实现术语属于源码内部语言而 Improved performance 这类宽泛表述又无法让用户感知任何具体收益。正确的写法应落在“用户能观察到什么变化”这一层。键盘快捷键统一用 kbd 标签包裹Issue 引用统一用 #[number] 格式。 ## 四、Validation Steps 最佳实践标签选择与测试指引 ### 4.1 标签选择原则 模板参考文档给出的选择规则为 - **功能标签**用于功能变更 - **平台标签**仅在需要平台相关测试时添加 - **:critical** 仅用于关键路径功能 - **不要过度打标签**聚焦主要受影响区域。 这套规则与 [test-tags.ts](https://link.gitcode.com/i/5a02c373cbf8053049fc1cd391930183#L6-L39) 的注释完全对应FeatureTags:console、:connections、:data-explorer、:duck-db 等运行在默认的 Linux/Electron 通道PlatformTags:win、:web、:rocky-electron、:workbench 系列等各自触发独立的 CI 任务:critical 具有特殊行为。从源码结构看[fetch-test-tags.sh](https://link.gitcode.com/i/1c165362e1e67f25ed618e9aa64d33ac) 正是按这三类外加 performance对标签做分类提取的。 ### 4.2 测试指引示例 **简单修复**:consoleRun any Python code in the console and verify output appears correctly.**复杂功能DuckDB 连接**:connections :duck-dbInstall DuckDB:pip install duckdbCreate connection via File New Connection DuckDBSelect In-memory database optionRun the test script:import duckdb conn duckdb.connect() conn.execute(CREATE TABLE test (id INT, name VARCHAR)) conn.execute(INSERT INTO test VALUES (1, test))Verify table appears in Connections paneDouble-click table to preview data复杂功能的测试指引应包含安装依赖、创建连接的完整路径、可执行代码脚本以及逐条验证步骤确保任何评审者都能复现。 ## 五、常见模式Paired PR、Breaking Changes 与文档更新 ### 5.1 Paired PRs跨仓库联动 PR 当 PR 依赖其他仓库的变更时明确标注合并顺序Related PRs (merge in order):posit-dev/ark#123 - Kernel support (merge first)This PR - UI integrationposit-dev/positron-python#456 - Language server support (optional)这一模式与 Positron 的多仓库架构ark 内核、positron-python 语言支持强相关[SKILL.md](https://link.gitcode.com/i/ca7252c8993ae48376de761cd2f447e1) 的工作流也把 Related PRs 作为标准上下文信息收集。 ### 5.2 Breaking Changes破坏性变更 必须包含迁移说明并给出 Before/After 对比⚠️ Breaking ChangesThis PR changes [what changes]. Users will need to [migration steps].Before:old_api_call()After:new_api_call(param)### 5.3 Documentation Updates文档更新 当 PR 配套文档变更时引用对应文档仓库的 PRDocumentation: posit-dev/positron-docs#789## 六、: 标签的 CI 触发机制为什么必须严守书写位置 这是本文要特别强调的**安全红线**。SKILL.md 的 Tag Safety 一节明确指出CI 的 [pr-tags-parse.sh](https://link.gitcode.com/i/5787e7d23a786e9f7021f191a2b9d55c) 用 grep -o :[a-zA-Z0-9_-]* 对 **PR Body 全文**做原始子串匹配它对 Markdown 结构毫无感知——一个字面上的 :tag 子串无论出现在哪个章节、是否在反引号代码块内、是真实指令还是行文中顺带提及都会触发对应套件的 CI 任务。反引号引用**不能**提供保护该行为已在 PR #14734 上确认。 因此规则是 1. **: 前缀的字面字符串只能出现在 Validation Steps 章节**且只能用于你确实希望 CI 运行的标签 2. 在 Summary、QA Notes、影响范围说明等其余位置一律用**不带 : 前缀**的名称指代测试区域例如写 the sessions, apps, and viewer suites而不要写成 :sessions :apps :viewer 作为括注 3. 即使 PR 本身是修复标签自动检测系统讨论标签机制时同样只能描述标签名称不能拼写出 : 形式 4. 提交前扫描草稿清除 Validation Steps 之外的所有 :。 从 [pr-tags-parse.sh](https://link.gitcode.com/i/5787e7d23a786e9f7021f191a2b9d55c#L152-L198) 的实现可以印证这一机制的完整链路脚本先探测 :all运行全部测试否则提取全部 : 标签过滤 :no-auto-tags 逃生舱口然后**对照 [test-tags.ts](https://link.gitcode.com/i/5a02c373cbf8053049fc1cd391930183) 枚举校验标签合法性**拼写错误的标签会被剔除并在 PR 评论中警告最后无条件补上 :critical 保底。此外脚本还会根据 PR 改动文件自动派生标签改动 ark 子模块自动注入 :ark、:win、:web通过 [test-tag-paths-map.json](https://link.gitcode.com/i/0b5ab650869f2c082890974136bfcfbb) 路径映射为源码改动派生功能标签除非作者写了 :no-auto-tags 显式退出。 ### 自动标签派生对写 PR 的启示 正因为 CI 会自动派生标签PR 作者在 Validation Steps 中**手写**的标签应当聚焦于自动派生覆盖不到的部分平台标签:win、:web、Rocky/openSUSE/SLES/Debian 系列必须作者手动添加才能开启对应平台通道而功能标签即使不写改动对应源码目录时也会被路径映射自动补上。这与模板参考文档“不要过度打标签聚焦主要受影响区域”的原则互为补充。 ## 七、风格指南语言与格式 ### 7.1 语言规范 - **现在时**描述行为Fixes、Adds、Enables - **主动语态**This PR fixes...而不是 The bug is fixed by... - **简洁**删掉一切多余词汇 - **面向用户**聚焦影响而非实现。 ### 7.2 格式规范 - 代码、命令、文件名使用反引号 - 强调用 **粗体**克制使用 - 键盘快捷键用 kbd 标签 - Issue 链接统一用 #[number] 格式 - 代码块带语言提示 python 、 bash 。 ### 7.3 应当避免的内容 - 华丽辞藻或不必要的上下文 - Release Notes 中的实现细节 - 道歉或自我贬低 - Commit 消息列表PR Body 应做总结而非罗列 - TODO 项应放到 Issue 中 - 疑问句在创建 PR 前解决所有问题。 ## 八、配套工作流Positron PR Helper Skill 仓库中的 [SKILL.md](https://link.gitcode.com/i/ca7252c8993ae48376de761cd2f447e1) 将上述模板落地为一个五步工作流 1. **收集上下文**Issue 编号、PR 类型、Summary、是否需要截图、关联 PR有 Issue 时用 gh issue view 拉取详情 2. **动态拉取测试标签**通过 [fetch-test-tags.sh](https://link.gitcode.com/i/1c165362e1e67f25ed618e9aa64d33ac) 从 test/e2e/infra/test-runner/test-tags.ts 提取当前完整标签清单脚本无需 TypeScript 编译通过 grep/sed 解析枚举支持 markdown、json、list 三种输出格式运行时间 1 秒 3. **PETE 测试覆盖评估**本地预览检查测试覆盖若判定 Insufficient 则必须补充具体测试建议不得用空泛的 Validation Steps 掩盖PR 打开后可在 CI 中通过 /pete 评论获取权威结论 4. **生成 PR Body**按类型模板组装开头行 → 描述/Summary → 截图 → Release Notes → Validation Steps 5. **输出**支持复制到剪贴板pbcopy仅 Mac、gh pr edit 更新既有 PR、写入文件或直接展示。 ## 结语 Positron 的 PR Body 规范本质上是一套“**人机双读**”约定人类评审者从 Summary 与 Release Notes 快速理解改动CI 系统则从 Validation Steps 的 : 标签精确调度 e2e 测试。遵循本文的模板结构、Release Notes 用户视角原则、标签选择规则并严守 : 标签只能出现在 Validation Steps 的红线就能让每一次代码合入既清晰可读又精准触发应有的测试覆盖。相关模板全文可查阅 [pr-templates.md](https://link.gitcode.com/i/c4abcdd76e8967cf629d265ece2fc924)标签定义与 CI 解析逻辑可分别深入 [test-tags.ts](https://link.gitcode.com/i/5a02c373cbf8053049fc1cd391930183) 与 [pr-tags-parse.sh](https://link.gitcode.com/i/5787e7d23a786e9f7021f191a2b9d55c)。赞分享开发工具代码编辑器数据科学【免费下载链接】positronPositron, a next-generation data science IDE项目地址https://gitcode.com/gh_mirrors/po/positron点击查看免费下载相关推荐Positron Playwright E2E 测试编写指南从测试结构、Fixtures 到防 Flaky 实战Positron Playwright E2E 测试编写指南从测试结构、Fixtures 到防 Flaky 实战 本指南以 Positron 仓库内置的 au开发工具代码编辑器数据科学Positron Playwright E2E 测试文件结构完全指南从目录组织到用例编写的官方规范Positron Playwright E2E 测试文件结构完全指南从目录组织到用例编写的官方规范 本篇技术指南以 Positron 官方测试规范文档 .cl开发工具代码编辑器数据科学ClickHouse 文档模板体系解析从参考模板到叙事指南的写作规范ClickHouse 文档模板体系解析从参考模板到叙事指南的写作规范 本文以 docs/_templates/ 目录中的模板文件为核心主体系统讲解 Clic数据库OLAP列式数据库大数据实时分析数据分析上一篇Doctrine Lexer源码级揭秘scan()中preg_split一行代码实现正则分词的全流程拆解下一篇Windows热键冲突终极解决方案5分钟快速找出占用快捷键的程序创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考