ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

WePY 开源贡献指南:从 Issue 提交、Fork PR 工作流到 Commit 规范与本地调试

WePY 开源贡献指南:从 Issue 提交、Fork PR 工作流到 Commit 规范与本地调试 WePY 开源贡献指南从 Issue 提交、Fork PR 工作流到 Commit 规范与本地调试【免费下载链接】wepy小程序组件化开发框架 - 已归档项目地址: https://gitcode.com/gh_mirrors/we/wepy导读本文是 WePY小程序组件化开发框架仓库的完整贡献者指南覆盖贡献者从提 Issue、Fork Pull Request 全流程、Commit 消息规范到本地构建与调试wepy build/wepy-dev build/wepy-debug build的完整闭环。读完本文你将掌握参与 WePY 开发的标准协作姿势如何提交一个合格的问题报告、如何以干净整洁的提交历史向主仓库提交代码、如何用仓库自带脚本完成构建、单测与断点调试并理解这些流程在仓库源码中的落地实现。一、参与方式概述Issue 与 Pull RequestWePY 欢迎所有开发者通过两种途径参与项目发展提 Issue反馈 bug、提出功能新增需求帮助维护者了解社区诉求提 Pull Request直接以代码形式贡献修复与特性是成为核心贡献者的主要路径。文档明确强调WePY 持续招募贡献者即使在 issue 中回答问题或者做一些简单的 bugfix也会给 WePY 带来很大的帮助。也就是说贡献的粒度没有门槛从答疑到修 bug 再到新功能都是被鼓励的。作为佐证仓库在 CONTRIBUTING.md 开头列出了多位早期核心贡献者dlhandsome、dolymood、baisheng、deepfunc、nishino-tsukasa并特别致谢了 dlhandsome 提交的 38 个 commits约 1,350 行增加、362 行删除截止 2018-02-28。这表明社区维护者重视持续、小步的贡献积累而非一次性的巨型提交。二、Issue 提交规范2.1 提 Issue 前的四个前置条件文档要求贡献者在提交 Issue 前逐条确认以下条件缺一不可必须是一个 bug 或者功能新增Issue 用于承载明确的问题或需求不接受与代码变更无关的闲聊必须是 WePY 相关问题原生小程序的问题请移步微信官方开发者社区不要在 WePY 仓库中混入非框架问题已经搜索过在已有 issue 中检索过且没有找到相似的 issue 或解决方案避免重复提交完善模板信息按照仓库提供的 issue 标准模板填写必要信息复现步骤、环境、期望行为等。实操提示满足以上条件后直接使用 GitHub 的 “New Issue” 按钮进入模板填写。清晰的问题描述含最小复现代码、运行环境、期望与实际的差异能显著提升维护者定位问题的效率。三、Pull Request 提交流程Fork 工作流WePY 采用标准的 Fork PR 协作模型。完整流程分为五步。3.1 Fork 仓库点击仓库页面右上角的Fork按钮将 WePY 仓库复制到你自己的 GitHub 账号下得到一个属于你的远程副本。3.2 Clone 已 Fork 的项目在你自己 fork 出的仓库页面复制 SSH 地址clone 到本地$ git clone gitgithub.com:yourname/wepy.git将yourname替换为你的 GitHub 用户名。若当前网络环境不支持 SSH也可改用 HTTPS 地址 clone。3.3 添加 WePY 上游仓库将 WePY 官方仓库作为第二个 remote 添加到本地仓库便于后续拉取最新代码$ git remote add name url # 例如 $ git remote add wepy gitgithub.com:Tencent/wepy.git这里name是你自定义的 remote 别名惯例使用upstream或wepyurl是上游仓库地址。添加后可用git remote -v验证本地会同时存在你的 fork通常名为origin和上游仓库两个远程。3.4 保持与 WePY 上游仓库的同步在开始新功能开发前务必把上游的最新提交同步到本地避免基于过期代码开发导致冲突$ git pull --rebase name branch # 等同于以下两条命令 $ git fetch name branch $ git rebase name/branch文档明确说明git pull --rebase是git fetchgit rebase的等价组合先用fetch从上游拉取远程分支再用rebase把本地提交变基到上游分支之上。--rebase与普通pull默认 merge的关键区别在于它会把你的本地提交重放到上游最新提交之后形成线性的提交历史避免产生多余的 merge commit让 PR 的 diff 更干净、更易评审。同步完成后将分支推送到你自己的 forkorigin再在 GitHub 上发起 Pull Request 即可。3.5 Commit 信息提交提交 commit 时消息格式必须遵循仓库的 commit 消息约定详见 CONTRIBUTING_COMMIT.md这样做的直接收益是可以自动生成CHANGELOG。这一机制在仓库配置中有完整落地根目录 package.json 中声明了changelog: lerna-changelog脚本通过 lerna.json 的conventionalCommits: true配置发布时基于 Conventional Commits 约定自动聚合生成更新日志package.json 的config.validate-commit-msg中列出了允许的 type 列表feat、fix、docs、style、refactor、perf、test、chore、revert、build、release等并设置了autoFix: true自动修复同文件husky.hooks注册了commit-msg: npx validate-commit-msg钩子任何不符合规范的提交都会在 commit-msg 阶段被拦截从机制上保证历史提交的规范性。四、Commit 消息规范详解本节内容依据仓库的 CONTRIBUTING_COMMIT.md是提交信息格式的权威约定参照 Angular 团队的 commit 规范制定。4.1 三段式结构提交信息由三个部分组成Header、Body、Footer。Header Body Footer其中Header 是必需的Body 和 Footer 可以省略。4.2 Headertype 与 subjectHeader 只有一行包含两个字段type必需和subject必需。type: subjecttype 的合法取值用于说明 commit 的类别type含义feat新功能featurefix修补 bugdoc文档documentationstyle格式不影响代码运行的变动如空格、分号refactor重构既不是新增功能也不是修改 bug 的代码变动test增加测试chore构建过程或辅助工具的变动与根目录 package.json 中validate-commit-msg允许的 types 列表对照可见提交钩子覆盖了比文档表格更广的类别额外包含perf、revert、build、release且lerna-changelog的 labels 配置 会将这些类别映射为 CHANGELOG 中的分组标签New Feature / Bug Fix / Documentation / Internal / Breaking Change。subject 的书写规则以动词开头使用第一人称现在时——比如写改变change而不是改变了changed结尾不加句号。。4.3 Body详细描述Body 是对本次 commit 的详细说明可以分成多行。下面是一个规范范例More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. Further paragraphs come after blank lines. - Bullet points are okay, too - Use a hanging indent注意要点每行建议控制在 72 个字符左右便于在各类终端与评审工具中阅读段落之间用空行分隔可以使用项目符号列表并采用悬挂缩进Body 应当说明代码变动的动机以及与以前行为的对比——即回答为什么改和改了什么行为差异而不仅是改了什么。4.4 FooterBreaking Changes 与关闭 IssueFooter 部分应包含两类信息(1) Breaking Changes(2) 关闭的 issue。Breaking Changes破坏性变更如果当前代码与上一个版本不兼容则 Footer 部分以BREAKING CHANGE开头后面跟对变动的描述、变动理由和迁移方法。文档提示此类使用较少了解即可。在仓库中这类提交会被 package.json 的 changelog labels 归入:boom: Breaking Change分组在发布时显著提示升级风险。通过 commit 关联 issue如果当前提交关联了某个 issue可以在 Footer 中这样写issue #2通过 commit 关闭 issue当提交合并到默认分支时提交信息里可以使用fix/fixes/fixed、close/closes/closed或resolve/resolves/resolved等关键词后接 issue 号即可自动关闭该 issueCloses #1需要特别注意的边界情况如果提交不是合入默认分支则不会真正关闭 issue但该 issue 下会显示相关引用信息表示曾有过关闭意图只有当分支最终合并到默认分支时issue 才会被正式关闭。4.5 完整示例下面是一个包含 Header、Body、Footer 的完整提交信息feat: 添加了分享功能 给每篇文章添加了分享功能 - 添加分享到微信功能 - 添加分享到朋友圈功能 Issue #1, #2 Closes #1对照解析Header 为feat: 添加了分享功能新功能 动词开头的简短描述Body 描述功能内容并列出两个子项Footer 先关联Issue #1, #2再用Closes #1关闭其中一个 issue。五、开发调试与测试仓库内置命令完成 commit 规范学习后开发者在实际改代码时使用仓库内置的 npm 脚本进行构建、监听与测试。以下是 CONTRIBUTING.md 给出的命令结合源码逐一说明。5.1 构建与监听# Build code $ npm run build # Watch $ npm run watch根目录 package.json 中build脚本为node ./scripts/build.js负责整体构建单包构建通过 rollup 完成scripts/config.js中定义了core、core-ant、redux、x、use-promisify、use-intercept等构建目标入口统一为packages/pkg/index.js或index.ant.js产物输出到对应dist/目录并注入版本号与版权 bannernpm run watch等价于chokidar **/*.wpy **/*.js -c npm run dev:all -i /dist/即监听.wpy与.js文件的变更自动触发重新编译并排除dist/目录避免循环触发。5.2 运行测试用例# Run test cases $ npm run testtest脚本为npm run lint -- --fix npm run test:cov即先执行 ESLint 自动修复对应lint: eslint ./ --ext .js再通过nyc运行带覆盖率统计的单测。测试的调度入口是 test/unit.js它维护了一份参与单测的包清单babel-plugin-import-regenerator、cli、compiler-less、compiler-sass、core、plugin-define、use-intercept、use-promisify等并逐个进入packages/name目录执行npm run test。例如packages/cli/package.json中的测试脚本为mocha ./test/core/**/*.test.js覆盖模板编译、hook、fileDep、tag 解析等核心模块。5.3 全局 CLI、本地 CLI 与调试 CLI 三者的区别$ wepy build # 通过 npm 安装的全局 wepy $ wepy-dev build # 本地仓库编译出的 wepy $ wepy-debug build # 使用 node --inspect 调试本地 wepy这三条命令对应三种不同的运行方式是贡献者在本地验证改动时的关键工具wepy build调用的是通过npm install -g wepy安装的全局 CLI使用的是 npm 上已发布的稳定版本wepy-dev build调用本地仓库编译出的 CLI 可执行文件。CLI 的命令入口定义在 packages/cli/bin/wepy.jsbin字段声明于 packages/cli/package.json支持init、build、list、new等子命令。build命令的-w/--watch监听文件改动、-o/--outputweapp/web、-p/--platformbrowser/wechat/qq、-s/--source、-t/--target、--no-cache等选项都定义于此实际编译入口为 packages/cli/bin/wepy-build.js它解析配置后调用core/compile.js执行编译管线wepy-debug build以node --inspect方式启动本地 CLI方便开发者用 Chrome DevTools / VS Code 附加调试器打断点排查编译问题。仓库的 scripts/build.sh 中也有对应的调试开关TEST_DEBUG时以node --inspect --debug-brk启动可作为参考。实操建议本地改动 CLI 源码后先npm run build重新编译再使用wepy-dev build在真实小程序项目上验证编译结果遇到编译链路内部问题时切到wepy-debug build附加调试器单步跟踪 packages/cli/core/compile.js 的编译流程。六、流程如何被仓库机制自动保障贡献流程并非只靠文档约束仓库通过自动化配置将规范落到了实处环节仓库机制配置位置提交前代码检查husky的pre-commit钩子执行npm run lintpackage.json推送前全量测试husky的pre-push钩子执行npm run testpackage.jsonCommit 格式校验commit-msg钩子执行npx validate-commit-msgtype 白名单与autoFix见config.validate-commit-msgpackage.jsonCHANGELOG 自动生成lerna-changeloglerna.json的conventionalCommits: true发布消息统一为chore(release): publish %slerna.json交互式规范提交npm run commit走 commitizencz-conventional-changelog引导生成合规消息package.json也就是说只要你的 commit 消息符合本文第四节的规范钩子会自动放行后续 CHANGELOG 也会自动归类反之格式不合规的提交会在commit-msg阶段被直接拦截这正是 CONTRIBUTING_COMMIT.md 强调格式约定的工程化原因。七、小结参与 WePY 开发的核心路径可以浓缩为五步fork 仓库 → clone 到本地 → 添加上游 remote 并 rebase 同步 → 按 commit 规范提交 → 发起 Pull Request。过程中严格遵循 CONTRIBUTING.md 的 Issue 四前置条件与 CONTRIBUTING_COMMIT.md 的三段式提交格式配合npm run build/npm run test/wepy-dev build/wepy-debug build完成本地验证与调试就能以标准化的姿势融入 WePY 的协作生态并让自己的每次贡献都自动沉淀进 CHANGELOG。【免费下载链接】wepy小程序组件化开发框架 - 已归档项目地址: https://gitcode.com/gh_mirrors/we/wepy创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表