IntelliJ 平台提交规范实战从 subject 格式到 Safe Push 全流程指南【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community对于任何向 IntelliJ Platform 类仓库如 intellij-community提交代码的开发者或 AI Agent 而言提交信息的规范性直接决定 CI 是否放行本仓库的 SafePush/Patronus 系统会拒绝格式错误的提交信息一条不合格的 subject 就意味着一次无效的 CI 往返。本文基于仓库中的提交规范文档.claude/skills/commits/SKILL.md完整讲解 IntelliJ 提交信息的 subject 与 body 写法、POSIX/PowerShell 下的安全提交输入方式并衔接 safe-push 推送流程帮助读者一次通过提交校验、避免 CI 浪费。一、为什么提交信息会被机器拒绝SafePush 的自动校验IntelliJ 社区仓库的提交推送并非直接写入受保护分支而是经由 Safe Push 工作流由 Patronus 系统驱动完成。正如 .claude/skills/safe-push/SKILL.md 所述Safe Push 会将改动推送到临时分支、触发必需 CI 检查通过后才合入目标分支如master。在这个过程中Patronus 会校验提交信息的格式因此一个格式错误的提交信息会导致整次 CI 校验失败白白浪费一次往返时间。这意味着提交信息不再只是写给人类协作者看的说明它同时是一份面向机器的结构化输入。规范的核心约束集中在两点subject主题行的格式与body正文的内容要求。二、Subject 行两种格式与硬性禁忌提交主题行只有两种合法形态对应两类不同性质的变更IDEA-12345 subject # 行为变更 —— 必须带 YouTrack 工单号无子系统前缀 label subsystem: subject # 明确的非行为变更2.1 行为变更必须关联工单凡属行为变更behavioral changesubject 必须以 YouTrack 工单号如IDEA-12345开头后跟空格与主题描述。规范还给出了一条实用的判定原则如果你不确定某次变更是否属于行为变更那它就是行为变更。也就是说默认按行为变更处理并挂上工单号是最稳妥的选择。2.2 非行为变更使用 label subsystem 前缀对于明确的非行为变更subject 采用labelsubsystem: 主题的结构。仓库规范允许的 label 只有以下 8 个label适用场景tests测试相关改动cleanup清理代码refactor重构不改变行为docs文档改动format格式化style风格调整setup构建/环境配置misc其他杂项文档中给出的示例tests cidr: migrate JUnit 5 coverage就是tests label cidr 子系统 主题的标准形态。2.3 绝对禁止的写法subject 不能以WIP、fixup!、squash!、amend!开头——这些前缀属于 Git 工作流内部记号会被机器拒绝禁用 Conventional Commits 风格即不能写fix(scope): ...这种形式。这两条是硬性红线违反即触发校验失败。三、Body 正文解释为什么而非改了什么规范对正文的要求同样严格除了机械性变更typo 修正、import 调整、格式化之外每一次提交都必须写正文——包括非生产代码的改动。正文的写作要点说明为什么做这次变更、做了什么决策代码 diff 已经展示了改了什么正文不需要复述正文必须使用ASD-STE100简化技术英语撰写这与仓库根目录 AGENTS.md 中Writing一节的要求一致。该节给出的关键约束包括句子不超过 25 个单词、插入语独立成句不要用双破折号包裹、保留冠词写 the session 而非 session、同一概念只用同一术语、说明省略了什么以及为什么若有要求的后缀如IJ-MR-100这样的请求编号放在独立的结尾段落中。下面是规范提供的完整示例可对照体会 subject body 后缀段的完整结构MRI-3589 harden single-flight recursion checks Track active single-flight computations in coroutine context so recursive awaits fail fast in both the owning coroutine and child coroutines. IJ-MR-100再看一个非行为变更的示例tests cidr: migrate JUnit 5 coverage Convert remaining JUnit 4 suites under cidr/coverage to JUnit 5. Parametrized tests now use MethodSource instead of the Theories runner.四、安全输入多行提交信息的分平台写法多行提交信息的输入方式因 shell 而异选错平台写法会直接产出畸形提交。4.1 POSIX shellstdin 带引号 heredoc在 Linux/macOS 的 POSIX shell 下通过-F -从标准输入读取提交信息并用带引号的 heredoc保证内容原样传入git commit -F - EOF IDEA-12345 concise subject Explain why the change was made and what was decided. EOF注意 heredoc 定界符必须加引号EOF防止 shell 对正文内容做变量展开或命令替换。4.2 PowerShell逐段 -m禁用 here-string规范明确警告在 Windows PowerShell 下不要用 here-string 管道喂给git commit -F -因为 Windows PowerShell 可能给第一行附加 Unicode BOM导致 subject 畸形而被 SafePush 拒绝。正确做法是每个段落用一个-m参数同样的形式也适用于git commit --amendgit commit -m IDEA-12345 concise subject -m Explain why the change was made and what was decided. -m IJ-MR-100提交或 amend 之后还应主动核验提交对象确认 subject 直接以工单号或 label 开头、没有隐藏 BOMgit cat-file commit HEAD4.3 草稿文件的存放位置不要在/tmp、/private/tmp或工作区之外的其他路径暂存提交信息——这既可能触发额外的文件系统访问审批也会在工作区外留下明文痕迹。如果确实需要可复用的草稿请放在仓库 gitignore 的out/目录下例如out/commit-message.txt。五、写提交前的检查步骤规范要求动笔前先做两个动作避免一次提交混入多类改动运行git status --short与git diff --stat确认改动范围只有对于非本人本会话产出的改动才需要完整阅读 diff且大 diff 应逐文件阅读坚持一个提交只做一件事——行为变更里不要夹带 cleanup 或 refactoring不确定时就拆分提交。这两个步骤与仓库 AGENTS 的模块规范相辅相成例如 AGENTS.md 要求修改*.iml、BUILD.bazel或.idea/文件后运行./build/jpsModelToBazelCommunityOnly.cmd这类构建/工程配置改动即对应 subject 中的setuplabel——提交信息的分类本质上是对改动边界的确认。六、提交后的推送衔接 safe-push 技能提交信息通过校验只是第一步推送环节同样有标准流程。规范文档明确指出推送请使用safe-push技能其详细指南位于 .claude/skills/safe-push/SKILL.md。仓库根目录的safePush.cmd脚本提供 CLI 访问方式基本用法如下# 推送当前 HEAD 到 master最常见 ./safePush.cmd HEAD:master # 推送指定提交到 master ./safePush.cmd commit-hash:master # 干跑只跑测试不推送 ./safePush.cmd -dry-run HEAD:master常用选项包括-autosquash自动 squash fixup! 提交默认开启、-dry-run跑测试但不推送、-emergency跳过测试直接推送仅限紧急情况、-verbose与-help。Safe Push 的典型流程为改动被推送到临时分支 → Patronus 触发必需 CI 检查测试、编译→ 失败的测试最多重试 4 次 → 全部通过后合入目标分支 → 通过 Slack/Space/Email 通知结果。启动后你会收到形如https://patronus.labs.jb.gg/robot/uuid的 Patronus URL其中uuid即为 robot id应打印给用户作为跟踪该次运行的主要句柄。关于紧急推送safe-push 指南强调-emergency仅适用于三类场景修复编译损坏、回滚破坏安装包的提交、修复.patronus/config.yaml配置错误而 Javadoc 错别字修复、因无关测试失败而跳测、赶时间跳过测试等均属严禁情形。七、扩展指引进一步阅读仓库中的相关规范本规范文档是 IntelliJ 社区仓库为 AI Agent 编写的技能指南体系的一部分相关主题还可以继续阅读正文写作语言规范仓库根目录 AGENTS.md 的Writing一节定义了 ASD-STE100 简化技术英语在注释、KDoc、提交信息、文档中的统一要求推送工作流细节.claude/skills/safe-push/SKILL.md 完整记录了 Safe Push CLI、紧急推送边界与 Bazel 测试环境变量env_inherit等排障信息技能总索引.claude/skills/INDEX.md注该文件在仓库中位于.agents/skills/INDEX.md的渲染源之外实际技能清单可参照.claude/skills/目录。结语总结一套可直接落地的提交检查清单先确认改动是否行为变更不确定即视为行为变更并挂工单号→按两种格式之一写 subjectIDEA-12345 subject或label subsystem: subject→除机械改动外写 ASD-STE100 正文说明为什么改与决策依据 →按平台选择安全输入方式POSIX 用-F - heredocPowerShell 用逐段-m→提交后核验git cat-file commit HEAD无 BOM →通过 safe-push 技能推送。遵循这套流程即可避免因提交信息格式问题造成的 CI 往返浪费让每一次提交都成为干净、可追溯、可被机器与人类共同理解的一次变更。【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考