LogicFlow 代码贡献指南：从 Issue 提交、PR 协作到 npm 发布全流程解析

LogicFlow 代码贡献指南从 Issue 提交、PR 协作到 npm 发布全流程解析【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow导读本文以 LogicFlow 仓库的贡献规范文档为主线完整梳理一个开源流程图编辑框架的协作开发流程如何提交高质量的 Issue、如何规范地发起 Pull Request、本地开发环境的搭建与测试、符合 Angular 规范的 Commit Message 写法以及基于语义化版本与 Changesets 的发布管理流程。与此同时本文结合仓库根目录的 package.json、scripts/publish-prerelease.mjs、jest.config.ts 以及 .github 下的模板文件逐一印证规范背后的实际工程实现帮助贡献者既会操作又懂原理。一、仓库概览贡献者需要先了解的项目结构LogicFlow 是一个面向业务自定义的流程图编辑框架仓库采用pnpm Turborepo Lerna的多包monorepo结构。在动手贡献之前先熟悉以下工程事实pnpm-workspace.yaml 声明了工作区范围packages/**、examples/**、sites/**、scripts均属于同一个 pnpm workspacelerna.json 采用version: independent独立版本策略由changesets/cli统一管理版本与 CHANGELOG 生成并且ignoreChanges中排除了**/*.md即纯文档改动不会触发版本变更turbo.json 定义了build:cjs、build:esm、build:umd等构建任务及其产物缓存lib/**、es/**、dist/**根 package.json 的engines字段要求node 16.0.0、pnpm 9.0.0preinstall脚本通过only-allow pnpm强制使用 pnpm 作为包管理器。也就是说任何 PR 提交、本地构建、测试与发布流程都建立在这套 pnpm workspace 之上。下文的所有命令均可在根目录 package.json 的scripts字段中找到对应定义。二、提交 Issues高质量反馈的第一步规范的 Issue 是高效协作的地基。贡献规范CONTRIBUTING.md明确要求确定 issue 的类型是 Bug、Feature Request 还是问题咨询避免意图模糊避免重复提交在提交之前搜索现有 Issue查看是否已有人反馈过相同问题明确意图在标签label、标题title或内容中清晰描述诉求。仓库通过 .github/ISSUE_TEMPLATE 下的 YAML 模板把意图明确落实为强制字段。以 BUG_REPORT_ZH.yml 为例提交 Bug 时必须填写发生了什么描述期望表现与实际表现的差异并提供文字描述、截图或可复现示例必填logicflow/core版本必填例如1.2.16logicflow/extension版本必填例如1.2.17logicflow/engine版本选填例如0.0.9浏览器与运行环境Firefox / Chrome / Safari / Microsoft Edge / NodeJS可多选。由于 packages 采用独立版本策略各包版本号互不相同反馈者明确核心、扩展、引擎三个包的版本号维护者才能快速定位回归点。此外 config.yml 允许开启空白 Issue并引导提问类话题进入 Discussions 讨论区。提交后LogicFlow 维护同学会确认 Issue 意图、更新合适的标签、关联 milestone 并指派开发者。三、提交代码完整的 PR 协作流程3.1 从分支创建到开发环境启动贡献规范给出的推荐流程是 fork 仓库、新建语义化分支、本地开发验证后提交 PR。核心命令如下# 先创建开发分支开发分支名应该有含义避免使用 update、tmp 之类的 $ git checkout -b branch-name # 监听 packages 源码变更热更新 es/lib 产物 $ pnpm run dev # 或 $ pnpm start # 首次或 clean 后先一次性构建es libdemo 开发所需 $ pnpm run build # 再另开终端进入 example 启动 demo $ cd examples/feature-examples pnpm dev # 开发完成后跑下测试是否通过必要时需要新增或修改测试用例 pnpm run test # 测试通过后提交代码message 见下面的规范 $ git add . # git add -u 删除文件 $ git commit -m fix(role): role.use must xxx $ git push origin branch-name从源码角度理解这几条命令的底层行为pnpm run dev对应根 package.json 中的dev: pnpm -r --parallel --filter./packages/* run dev会并行监听所有 packages 的源码变更各 package 内部的dev由rssrun-shared-scripts从根配置继承——即同时以 watch 模式产出 CJSlib/与 ESMes/产物pnpm run build对应build: turbo run build --filter./packages/*由 Turborepo 按依赖拓扑执行各包的build:cjsbuild:esm产物的lib/**、es/**会被缓存复用pnpm run test对应根目录的test: jest。Jest 配置见 jest.config.ts使用jest-environment-jsdom通过moduleNameMapper将logicflow/core、logicflow/extension直接映射到packages/*/src/index.ts源码因此测试无需构建即可运行jest.setup.ts 还 Mock 了 jsdom 中缺失的ResizeObserver。测试目录分布在packages/core/__tests__、packages/extension/__test__、packages/layout/__test__、packages/engine/__test__等位置。3.2 代码风格必须通过 ESLint贡献规范要求代码风格必须通过 ESLint并提供了本地检查命令$ pnpm run lint:ts该命令在根 package.json 中的定义为lint:ts: eslint **/src/**/*.{js,ts}?(x) --cache --fix。此外根配置中还集成了 Prettierpnpm run prettier、stylelint*.less文件、husky lint-staged commitlintcommitlint 基于commitlint/config-conventional在提交阶段拦截不符合规范的 Commit Messagelint-staged 则只对暂存文件做格式化与 lint保证提交进入仓库前已经过工程化检查。3.3 PR 中需要提供的信息由于谁也无法保证过了多久之后还记得多少贡献规范要求发起 PR 时至少提供以下四类信息以便后期回溯历史需求点一般关联 Issue 或者注释都算升级原因不同于 Issue简要描述为什么要处理框架测试点可关联到测试文件说明关键验证点即可关注点面向使用者可以没有一般指不兼容更新等需要额外提示的内容。仓库的 .github/workflows/PULL_REQUEST_TEMPLATE.md 将这一要求固化为 PR 表单模板包含 Description变更细节、Motivation and Context为什么需要这次变更若修复 Issue 需链接、变更类型勾选Bug fix / New feature / Breaking change / Enhancement / Refactoring / Test Case / 代码风格优化 / Docs / Chore以及合并前的自检清单代码风格、文档同步、新增测试、全部测试通过等。四、Commit Message 规范Angular 约定式提交为了让 history 更清晰并可自动生成 CHANGELOGLogicFlow 采用 Angular 规范的约定式提交格式type(scope): subject BLANK LINE body BLANK LINE footer4.1 type提交类型type含义feat新功能fix修复问题docs修改文档style修改代码格式不影响代码逻辑refactor重构代码理论上不影响现有功能perf提升性能test增加或修改测试用例chore修改工具相关包括但不限于文档、代码生成等deps升级依赖4.2 scope / subject / body / footerscope修改文件的范围如fix(role)中的role表示影响的是 role 相关模块subject用一句话清楚描述本次提交做了什么body补充 subject适当增加原因、目的等背景信息也可不写footer当存在非兼容修改Breaking Change时必须在此处描述清楚可关联相关 Issue如Closes #1, Closes #2, #3。4.3 完整示例贡献规范给出的示例fix($compile): [BREAKING_CHANGE] couple of unit tests for IE9 Older IEs serialize html uppercased, but IE9 does not... Would be better to expect case insensitive, unfortunately jasmine does not allow to user regexps for throw expectations. Document change on logicflow/core#12 Closes #392 BREAKING CHANGE: Breaks foo.bar api, foo.baz should be used instead示例中同时演示了fix scope 表达修复范围、body 说明问题背景与解决思路、Closes #392自动关闭关联 Issue以及BREAKING CHANGE:区块声明 API 破坏性变更。这套格式之所以重要是因为 Changesets 的changeset version会基于这些约定式提交生成 CHANGELOG见下文发布管理。五、发布管理从 master 分支到 npm 全流程LogicFlow 基于 semver语义化版本号进行发布。整个发布体系由分支策略与发布策略两部分构成。5.1 分支策略master分支为当前稳定发布的版本所有开发都直接从master切出分支进行所有 API 的废弃都需要在当前稳定版本上给出deprecated提示并保证在稳定版本上一直兼容到新版本发布。5.2 发布策略负责人的阶段职责每个大版本发布都有专门的负责人在不同阶段承担不同职责准备工作建立 milestone确认需求关联 milestone指派和更新 issues。发布前确认当前 Milestone 的所有 Issue 都已关闭或可延期完成性能测试编写发布说明Release Notes / History修正文档中与版本相关的内容指定下一个大版本的负责人。发布时将老的稳定版本master备份到以当前大版本为名字的分支上例如1.x并设置 tag 为{v}.x例如1.x发布新的稳定版本到 npm并通知上层框架进行更新npm publish之前需要先确认发布环境与账号权限。5.3 版本管理的工程化底座Changesets 独立版本.github/workflows/release.yml 展示了自动化的一环当代码推送到main分支时GitHub Actions 会运行pnpm install并调用changesets/actionv1自动创建 Release PR。结合 lerna.json 的version: independent与command: { version: { conventionalCommits: true } }配置可以推断仓库刻意采用Changesets 累积 集中消费的模式——开发者日常只负责写.changeset/*.md变更说明文件版本号与 CHANGELOG 的生成被集中到发布环节。5.4 Prerelease内网/预发布测试贡献规范给出的 Prerelease 命令pnpm publish:pre # 发布 alpha 包默认 pnpm publish:pre beta # 发布 beta 包这两个命令对应根 package.json 中的publish:pre: node scripts/publish-prerelease.mjs其真实执行逻辑见 scripts/publish-prerelease.mjspnpm test先跑全部测试pnpm buildpnpm build:umd完成 CJS/ESM/UMD 构建pnpm changeset version --snapshot ${tag}生成临时快照版本号形如2.3.0-alpha-20260705-abc123pnpm changeset publish --tag ${tag} --registryhttps://registry.npmjs.org以对应 tag默认alpha可传参beta发布到 npmfinally块中通过git checkout -- packages/*/package.json还原 package.json——快照版本号永远不允许被提交。脚本头部注释明确说明了两点关键设计.changeset/*.md文件不会被消费继续累积留待正式发布统一生成完整 CHANGELOG因此 prerelease 与 stable release 之间不会丢失任何变更记录。5.5 Stable Release对外正式发布正式发布三步走pnpm changeset version— 消费所有累积的 changeset 文件生成完整 CHANGELOG更新版本号git add . git commit -m chore: version packages— 提交版本变更pnpm publish:only— 发布到 npm。其中pnpm publish:only在根 package.json 中定义为publish:only: pnpm test changeset publish --registryhttps://registry.npmjs.org发布前会再次执行完整测试作为质量闸门随后才由changeset publish依据各 package.json 的版本号将logicflow/core、logicflow/extension、logicflow/layout等包发布到 npm 官方 registry。注意该步骤不会执行构建因此正式发布前必须保证es/、lib/、dist/产物已通过前面流程生成完毕。六、写给贡献者的实战建议结合上述全流程给希望参与 LogicFlow 贡献的开发者几条实操建议先小后大从docs、test、fix类改动入手熟悉 pnpm workspace 与 Jest 测试组织方式各 package 的__tests__/__test__目录后再触碰核心逻辑本地闭环pnpm run dev热更新产物 →cd examples/feature-examples pnpm dev启动 demo 验证交互 →pnpm run test跑回归 →pnpm run lint:ts过代码风格形成完整开发闭环Commit 一次到位遵循type(scope): subject格式并善用Closes #xx与BREAKING CHANGE:区块避免提交被 husky commitlint 拦截发布由维护者主导贡献者通常不需要关心 Prerelease / Stable Release 的发布命令但理解 scripts/publish-prerelease.mjs 中快照版本不落地、changeset 文件累积消费的设计有助于正确书写.changeset/*.md变更说明让整个发布链路顺畅运转。参考与延伸阅读CONTRIBUTING.md本文依据的贡献规范原文package.json全部开发、构建、测试、发布脚本的定义scripts/publish-prerelease.mjsPrerelease 发布脚本的完整实现lerna.json 与 turbo.json版本管理与构建编排配置jest.config.ts 与 jest.setup.ts测试环境配置.github/workflows/PULL_REQUEST_TEMPLATE.md、.github/ISSUE_TEMPLATE/BUG_REPORT_ZH.yml、.github/workflows/release.ymlIssue、PR 与自动化发布的工程化模板。【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考