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 Request

WePY 欢迎所有开发者通过两种途径参与项目发展：

提 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 git@github.com:<yourname>/wepy.git

将<yourname>替换为你的 GitHub 用户名。若当前网络环境不支持 SSH，也可改用 HTTPS 地址 clone。

3.3 添加 WePY 上游仓库

将 WePY 官方仓库作为第二个 remote 添加到本地仓库，便于后续拉取最新代码：

$ git remote add <name> <url> # 例如： $ git remote add wepy git@github.com:Tencent/wepy.git

这里<name>是你自定义的 remote 别名（惯例使用upstream或wepy），<url>是上游仓库地址。添加后可用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 fetch+git rebase的等价组合：先用fetch从上游拉取远程分支，再用rebase把本地提交变基到上游分支之上。--rebase与普通pull（默认 merge）的关键区别在于：它会把你的本地提交"重放"到上游最新提交之后，形成线性的提交历史，避免产生多余的 merge commit，让 PR 的 diff 更干净、更易评审。

同步完成后，将分支推送到你自己的 fork（origin），再在 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 Header：type 与 subject

Header 只有一行，包含两个字段：type（必需）和subject（必需）。

<type>: <subject>

type 的合法取值（用于说明 commit 的类别）：

type	含义
`feat`	新功能（feature）
`fix`	修补 bug
`doc`	文档（documentation）
`style`	格式（不影响代码运行的变动，如空格、分号）
`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 Footer：Breaking Changes 与关闭 Issue

Footer 部分应包含两类信息：(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 号即可自动关闭该 issue：

Closes #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/目录，并注入版本号与版权 banner）；
npm run watch等价于chokidar '**/*.wpy' '**/*.js' -c 'npm run dev:all' -i '/dist/'，即监听.wpy与.js文件的变更自动触发重新编译，并排除dist/目录避免循环触发。

5.2 运行测试用例

# Run test cases $ npm run test

test脚本为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.js，bin字段声明于 packages/cli/package.json，支持init、build、list、new等子命令。build命令的-w/--watch（监听文件改动）、-o/--output（weapp/web）、-p/--platform（browser/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 lint`	package.json
推送前全量测试	`husky`的`pre-push`钩子执行`npm run test`	package.json
Commit 格式校验	`commit-msg`钩子执行`npx validate-commit-msg`，type 白名单与`autoFix`见`config.validate-commit-msg`	package.json
CHANGELOG 自动生成	`lerna-changelog`+`lerna.json`的`conventionalCommits: true`，发布消息统一为`chore(release): publish %s`	lerna.json
交互式规范提交	`npm run commit`走 commitizen（`cz-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），仅供参考