Wails 贡献指南v2 与 v3 双轨开发、变更日志与 WEP 提案流程全解析【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wailsWails 是一个使用 Go 构建桌面应用的开源框架当前仓库同时维护 v2稳定版与 v3beta两条开发轨道。本文基于仓库根目录的 CONTRIBUTING.md 展开系统讲解双轨源码布局、Pull Request 检查清单、MIT 许可与代码来源规范并深入剖析 v3 特有的 Wails Enhancement ProposalWEP提案流程与自动化变更日志机制帮助贡献者准确选择提交路径、避免踩坑。一、总览Wails 的双轨贡献模型Wails 仓库目前维护两条并行开发轨道贡献者需要根据改动目标选择正确的轨道而不是笼统地向master 分支提交轨道状态源码目录变更日志位置详细贡献文档v2稳定版stablev2/website/src/pages/changelog.mdx[Unreleased]标题下wails.io 网站文档v3betav3/v3/UNRELEASED_CHANGELOG.mdPR 合并时自动生成v3.wails.io 贡献文档从仓库结构可以清晰看到这种双轨布局v2/下包含cmd/wailsCLI 工具、internal/app、binding、frontend 等核心实现、pkg/application、runtime、menu 等公共 API以及examples/而v3/则独立拥有pkg/application349 个文件的完整应用层、internal/commands147 个文件构建/打包/运行命令、internal/runtime、internal/generator等一整套全新实现。两者源码互不共享目录贡献时切勿混淆。对于 v3贡献文档还特别强调任何新功能和对公共行为的改动都需要先提交一份 Wails Enhancement ProposalWEP以 Draft PR 的形式开启而不是提交 feature-request issue。可选地可以在 Discussions 的 Ideas 分类中进行早期讨论。二、Pull Request 检查清单无论选择哪条轨道提交 PR 前都应逐项核对以下要求来自 CONTRIBUTING.md一个 PR 只做一件事一个 feature 或一个 fix避免混合提交导致评审困难。更新对应的变更日志文件v2在 website/src/pages/changelog.mdx 的[Unreleased]标题下追加条目该文件第 15 行即## [Unreleased]小节v3v3 的条目会在 PR 合并时由自动化工具自动生成。如果想控制措辞可以在 v3/UNRELEASED_CHANGELOG.md 中手动添加自己的条目自动化流程会优先使用它。遵循所改动区域的既有代码风格贴合当前目录下已有代码的组织方式与命名习惯。在合理之处补充测试仓库中 v2 的internal/binding/binding_test/30 个测试文件、internal/project/project_test.go、v3/test/下的4424-event-block、4769-menu等回归测试目录以及v3/scripts下的auto-changelog_test.go、validate-changelog_test.go等都是可以参照的测试组织范例。2.1 v3 变更日志的自动化机制v3 的变更日志自动化体现在 v3/scripts/auto-changelog.go 中。从源码看其工作流程如下读取环境变量PR_NUMBER、GITHUB_TOKEN、OPENROUTER_API_KEY、GITHUB_REPOSITORY第 38-46 行缺失时直接报错退出抓取 PR 信息与 CodeRabbit 机器人的 walkthrough 评论作为上下文fetchPR、fetchCodeRabbitWalkthrough第 106-168 行若 PR 标题是ci、chore、build、test、style等内部类型isInternalChange第 381-400 行则跳过生成这类改动不会出现在用户可见的 release notes 中调用 OpenRouter 上的google/gemini-2.5-flash-lite模型生成条目第 402-479 行要求输出sectionAdded/Changed/Fixed/Deprecated/Removed/Security 之一与entry通过sanitizeEntry第 487-503 行对模型输出做安全净化折叠空白、剥离 HTML 标签、移除 Markdown 链接/图片/代码语法硬性截断到 120 字符防止注入内容破坏 changelog 的 Markdown 结构最后调用insertEntry第 505-522 行把条目插入 v3/UNRELEASED_CHANGELOG.md 对应小节标题之后。配套的 v3/scripts/publish-changelog.py 负责把生成的条目发布回 master它在临时 detached worktree 中刷新origin/master、做重复条目检测已在 changelog 或归档中出现则跳过再提交并推送带 5 次重试与去重保护避免把贡献者本地未合并的改动一起推上去。因此v3 贡献者通常无需手动编写 changelog只有当希望精确控制措辞时才在 PR 中自行向 v3/UNRELEASED_CHANGELOG.md 添加条目。该文件本身带有详细说明注释Keep a Changelog 格式、使用现在时、必要时引用 issue/PR 编号、由 nightly release 流程处理后重置条目应放在## Added、## Changed、## Fixed、## Deprecated、## Removed、## Security六个预置小节之一。三、Wails Enhancement ProposalWEP流程WEP 是 v3 轨道中新功能/公共行为变更的正式提案记录以 PR 形式提交而不是 feature-request issue。完整流程定义在 v3/wep/README.md分为创建 WEP与实施 WEP两大部分。3.1 什么时候需要 WEP规则很简单需要 WEP新功能、新的公共 API 或选项、公共行为变更、破坏性变更、跨平台工作、重要的平台专属工作。不需要 WEP已确认的 bug 修复、纯文档改动、无外部可观察行为变化的内部重构——这些走标准 PR 流程即可。如果不确定可以在 GitHub Discussions 的 Ideas 分类或 Discord 上先询问。3.2 创建 WEP 的步骤构思可选先在 Ideas 分类或 Discord 上试探想法避免与既有规划重叠。撰写文档新建目录v3/wep/proposals/提案名称/将模板 v3/wep/WEP_TEMPLATE.md 复制为名称/proposal.md模板中所有小节Title、Summary、Motivation、Detailed Design、Non-Goals、Platform Considerations、Pros/Cons、Alternatives Considered、Backwards Compatibility、Security and Privacy、Test Plan、Reference Implementation、Maintenance Plan、Conclusion一个都不能删除图片、图表等附加资源放入提案目录。提交 Draft PR标题格式为[WEP] 标题PR 只包含提案文件与附加资源并在 PR 描述中写摘要。社区讨论PR 是官方讨论场所可在 Discord 的#enhancement-proposals频道分享反馈以 PR 评论形式沉淀最终需要有人可以是提案者本人承诺实施讨论成熟后把 PR 状态改为Ready for Review。评审周期社区反馈与讨论至少留出2 周。最终决定由 Wails 维护者基于社区反馈与技术价值兼容性、维护成本、与 Wails 的契合度作出裁决决定以固定格式评论在 PR 上**Decision**: Accepted / Rejected **Decided by**: maintainer(s) **Rationale**: A short explanation of the decision.被接受分配下一个 WEP 编号目录重命名为NNNN-提案名称状态更新为Accepted加入 WEP IndexPR 合并。被拒绝PR 关闭但仍记录在 WEP Index 中并附上决定链接便于日后想法再次出现时追溯。注意如果提案长期未获足够支持或超过一个月无进展可能以Withdrawn状态关闭。3.3 实施 WEP提案被接受后进入实施阶段开发按 Wails 编码规范实现开发过程中同步完善文档完成后提交实现 PR。反馈与迭代根据社区反馈改进。合并处理评审意见后合并 PR随后把 WEP 状态更新为Implemented并在 WEP Index 中补充实现 PR 链接。注意接受即意味着有承诺的实施者。若接受后3 个月内未启动实施该 WEP 会被标记为up for grabs任何人都可以接手。3.4 WEP Index 与状态机当前 WEP Index位于 v3/wep/README.md记录了一个已完成提案WEP标题状态提案实现0001Customising Window ControlsImplementedPR #3508PR #3508WEP 状态共五种Draft讨论中、Accepted已批准等待实施、Implemented已发布、Rejected被拒绝、Withdrawn作者关闭或长期无进展。仓库中已有一个完整的实现范例v3/wep/proposals/0001-titlebar-buttons/proposal.md自定义窗口控制2024-05-20 创建状态 Implemented。该提案是理解 WEP 文档质量的绝佳样板它定义了ButtonState枚举ButtonEnabled/ButtonDisabled/ButtonHidden为WebviewWindowOptions增加MinimiseButtonState、MaximiseButtonState、CloseButtonState三个字段为Window接口新增SetMinimizeButtonState、SetMaximizeButtonState、SetCloseButtonState方法并给出 Windows 上通过ExStyle字段如w32.WS_EX_TOOLWINDOW控制窗口扩展样式的完整可运行示例代码还明确记录了平台差异Windows 无法单独隐藏最小化/最大化按钮、非向后兼容的风险以及自绘标题栏这一被否决的替代方案——这正是 WEP 模板中 Detailed Design、Platform Considerations、Backwards Compatibility、Alternatives Considered 各小节的落地示范。四、许可与代码来源Licence and ProvenanceWails 以 MIT 许可 发布贡献同样以该条款进入项目。打开 Pull Request 即代表你确认以下三点原创性贡献内容为你本人所写或你有权提交它许可授权你同意以 MIT 许可授权给项目第三方代码合规其中包含的任何第三方代码均兼容许可且其来源与许可证已在 PR 中声明。关于流程有两点值得注意无需签署 CLA也无需添加 sign-off 尾注区别于 Linux 内核等要求 Signed-off-by 的项目。不确定就别合并后再说如果对某段代码能否安全贡献没有把握请在 PR 合并之前提问而不是合并之后。已发布的代码再梳理来源provenance要困难得多。这一原则与 website/src/pages/community-guide.mdx 中描述的社区协作方式一脉相承Wails 是社区驱动的开源项目可通过开发新功能、修复 bug、测试、撰写文档/教程、在 issues 和 discussions 中帮助他人等多种方式参与。五、常见疑问速查Q我要给 v3 提交一个 bug 修复需要 WEP 吗不需要。已确认的 bug 修复走标准 PR 流程只有新功能、公共 API 或公共行为变更才需要 WEP。Qv3 的 changelog 我要自己写吗默认不需要PR 合并时 v3/scripts/auto-changelog.go 会自动生成条目。想精确控制措辞时可自行向 v3/UNRELEASED_CHANGELOG.md 添加条目。Q我的 v3 PR 标题是chore: bump dependency会被记入 release notes 吗不会。ci/chore/build/test/style类型被判定为内部改动见 v3/scripts/auto-changelog.go 第 381-400 行自动化流程会跳过 changelog 条目。QWEP 被接受了是不是马上就能合并代码不是。接受只是通过提案评审还需要有承诺的实施者完成开发、提交实现 PR、通过评审后才合并之后状态才会更新为Implemented。六、总结Wails 的贡献体系围绕双轨v2 稳定 / v3 beta 分级流程标准 PR / WEP 提案 自动化变更日志三根支柱构建v2 与 v3 源码完全分离变更日志各自独立维护v3 的新功能一律经 WEP 提案Draft PR → 2 周社区讨论 → 维护者裁决 → 编号入册 → 实施合并确保公共行为的每一次演进都有公开的设计依据与可追溯记录自动化脚本则把模型生成与安全净化、去重发布结合起来在提升效率的同时守护 changelog 的数据完整性。无论你贡献的是代码、文档还是测试遵循本指南即可让改动被高效地评审、记录并最终惠及整个 Wails 社区。【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Wails 贡献指南：v2 与 v3 双轨开发、变更日志与 WEP 提案流程全解析
Wails 贡献指南v2 与 v3 双轨开发、变更日志与 WEP 提案流程全解析【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wailsWails 是一个使用 Go 构建桌面应用的开源框架当前仓库同时维护 v2稳定版与 v3beta两条开发轨道。本文基于仓库根目录的 CONTRIBUTING.md 展开系统讲解双轨源码布局、Pull Request 检查清单、MIT 许可与代码来源规范并深入剖析 v3 特有的 Wails Enhancement ProposalWEP提案流程与自动化变更日志机制帮助贡献者准确选择提交路径、避免踩坑。一、总览Wails 的双轨贡献模型Wails 仓库目前维护两条并行开发轨道贡献者需要根据改动目标选择正确的轨道而不是笼统地向master 分支提交轨道状态源码目录变更日志位置详细贡献文档v2稳定版stablev2/website/src/pages/changelog.mdx[Unreleased]标题下wails.io 网站文档v3betav3/v3/UNRELEASED_CHANGELOG.mdPR 合并时自动生成v3.wails.io 贡献文档从仓库结构可以清晰看到这种双轨布局v2/下包含cmd/wailsCLI 工具、internal/app、binding、frontend 等核心实现、pkg/application、runtime、menu 等公共 API以及examples/而v3/则独立拥有pkg/application349 个文件的完整应用层、internal/commands147 个文件构建/打包/运行命令、internal/runtime、internal/generator等一整套全新实现。两者源码互不共享目录贡献时切勿混淆。对于 v3贡献文档还特别强调任何新功能和对公共行为的改动都需要先提交一份 Wails Enhancement ProposalWEP以 Draft PR 的形式开启而不是提交 feature-request issue。可选地可以在 Discussions 的 Ideas 分类中进行早期讨论。二、Pull Request 检查清单无论选择哪条轨道提交 PR 前都应逐项核对以下要求来自 CONTRIBUTING.md一个 PR 只做一件事一个 feature 或一个 fix避免混合提交导致评审困难。更新对应的变更日志文件v2在 website/src/pages/changelog.mdx 的[Unreleased]标题下追加条目该文件第 15 行即## [Unreleased]小节v3v3 的条目会在 PR 合并时由自动化工具自动生成。如果想控制措辞可以在 v3/UNRELEASED_CHANGELOG.md 中手动添加自己的条目自动化流程会优先使用它。遵循所改动区域的既有代码风格贴合当前目录下已有代码的组织方式与命名习惯。在合理之处补充测试仓库中 v2 的internal/binding/binding_test/30 个测试文件、internal/project/project_test.go、v3/test/下的4424-event-block、4769-menu等回归测试目录以及v3/scripts下的auto-changelog_test.go、validate-changelog_test.go等都是可以参照的测试组织范例。2.1 v3 变更日志的自动化机制v3 的变更日志自动化体现在 v3/scripts/auto-changelog.go 中。从源码看其工作流程如下读取环境变量PR_NUMBER、GITHUB_TOKEN、OPENROUTER_API_KEY、GITHUB_REPOSITORY第 38-46 行缺失时直接报错退出抓取 PR 信息与 CodeRabbit 机器人的 walkthrough 评论作为上下文fetchPR、fetchCodeRabbitWalkthrough第 106-168 行若 PR 标题是ci、chore、build、test、style等内部类型isInternalChange第 381-400 行则跳过生成这类改动不会出现在用户可见的 release notes 中调用 OpenRouter 上的google/gemini-2.5-flash-lite模型生成条目第 402-479 行要求输出sectionAdded/Changed/Fixed/Deprecated/Removed/Security 之一与entry通过sanitizeEntry第 487-503 行对模型输出做安全净化折叠空白、剥离 HTML 标签、移除 Markdown 链接/图片/代码语法硬性截断到 120 字符防止注入内容破坏 changelog 的 Markdown 结构最后调用insertEntry第 505-522 行把条目插入 v3/UNRELEASED_CHANGELOG.md 对应小节标题之后。配套的 v3/scripts/publish-changelog.py 负责把生成的条目发布回 master它在临时 detached worktree 中刷新origin/master、做重复条目检测已在 changelog 或归档中出现则跳过再提交并推送带 5 次重试与去重保护避免把贡献者本地未合并的改动一起推上去。因此v3 贡献者通常无需手动编写 changelog只有当希望精确控制措辞时才在 PR 中自行向 v3/UNRELEASED_CHANGELOG.md 添加条目。该文件本身带有详细说明注释Keep a Changelog 格式、使用现在时、必要时引用 issue/PR 编号、由 nightly release 流程处理后重置条目应放在## Added、## Changed、## Fixed、## Deprecated、## Removed、## Security六个预置小节之一。三、Wails Enhancement ProposalWEP流程WEP 是 v3 轨道中新功能/公共行为变更的正式提案记录以 PR 形式提交而不是 feature-request issue。完整流程定义在 v3/wep/README.md分为创建 WEP与实施 WEP两大部分。3.1 什么时候需要 WEP规则很简单需要 WEP新功能、新的公共 API 或选项、公共行为变更、破坏性变更、跨平台工作、重要的平台专属工作。不需要 WEP已确认的 bug 修复、纯文档改动、无外部可观察行为变化的内部重构——这些走标准 PR 流程即可。如果不确定可以在 GitHub Discussions 的 Ideas 分类或 Discord 上先询问。3.2 创建 WEP 的步骤构思可选先在 Ideas 分类或 Discord 上试探想法避免与既有规划重叠。撰写文档新建目录v3/wep/proposals/提案名称/将模板 v3/wep/WEP_TEMPLATE.md 复制为名称/proposal.md模板中所有小节Title、Summary、Motivation、Detailed Design、Non-Goals、Platform Considerations、Pros/Cons、Alternatives Considered、Backwards Compatibility、Security and Privacy、Test Plan、Reference Implementation、Maintenance Plan、Conclusion一个都不能删除图片、图表等附加资源放入提案目录。提交 Draft PR标题格式为[WEP] 标题PR 只包含提案文件与附加资源并在 PR 描述中写摘要。社区讨论PR 是官方讨论场所可在 Discord 的#enhancement-proposals频道分享反馈以 PR 评论形式沉淀最终需要有人可以是提案者本人承诺实施讨论成熟后把 PR 状态改为Ready for Review。评审周期社区反馈与讨论至少留出2 周。最终决定由 Wails 维护者基于社区反馈与技术价值兼容性、维护成本、与 Wails 的契合度作出裁决决定以固定格式评论在 PR 上**Decision**: Accepted / Rejected **Decided by**: maintainer(s) **Rationale**: A short explanation of the decision.被接受分配下一个 WEP 编号目录重命名为NNNN-提案名称状态更新为Accepted加入 WEP IndexPR 合并。被拒绝PR 关闭但仍记录在 WEP Index 中并附上决定链接便于日后想法再次出现时追溯。注意如果提案长期未获足够支持或超过一个月无进展可能以Withdrawn状态关闭。3.3 实施 WEP提案被接受后进入实施阶段开发按 Wails 编码规范实现开发过程中同步完善文档完成后提交实现 PR。反馈与迭代根据社区反馈改进。合并处理评审意见后合并 PR随后把 WEP 状态更新为Implemented并在 WEP Index 中补充实现 PR 链接。注意接受即意味着有承诺的实施者。若接受后3 个月内未启动实施该 WEP 会被标记为up for grabs任何人都可以接手。3.4 WEP Index 与状态机当前 WEP Index位于 v3/wep/README.md记录了一个已完成提案WEP标题状态提案实现0001Customising Window ControlsImplementedPR #3508PR #3508WEP 状态共五种Draft讨论中、Accepted已批准等待实施、Implemented已发布、Rejected被拒绝、Withdrawn作者关闭或长期无进展。仓库中已有一个完整的实现范例v3/wep/proposals/0001-titlebar-buttons/proposal.md自定义窗口控制2024-05-20 创建状态 Implemented。该提案是理解 WEP 文档质量的绝佳样板它定义了ButtonState枚举ButtonEnabled/ButtonDisabled/ButtonHidden为WebviewWindowOptions增加MinimiseButtonState、MaximiseButtonState、CloseButtonState三个字段为Window接口新增SetMinimizeButtonState、SetMaximizeButtonState、SetCloseButtonState方法并给出 Windows 上通过ExStyle字段如w32.WS_EX_TOOLWINDOW控制窗口扩展样式的完整可运行示例代码还明确记录了平台差异Windows 无法单独隐藏最小化/最大化按钮、非向后兼容的风险以及自绘标题栏这一被否决的替代方案——这正是 WEP 模板中 Detailed Design、Platform Considerations、Backwards Compatibility、Alternatives Considered 各小节的落地示范。四、许可与代码来源Licence and ProvenanceWails 以 MIT 许可 发布贡献同样以该条款进入项目。打开 Pull Request 即代表你确认以下三点原创性贡献内容为你本人所写或你有权提交它许可授权你同意以 MIT 许可授权给项目第三方代码合规其中包含的任何第三方代码均兼容许可且其来源与许可证已在 PR 中声明。关于流程有两点值得注意无需签署 CLA也无需添加 sign-off 尾注区别于 Linux 内核等要求 Signed-off-by 的项目。不确定就别合并后再说如果对某段代码能否安全贡献没有把握请在 PR 合并之前提问而不是合并之后。已发布的代码再梳理来源provenance要困难得多。这一原则与 website/src/pages/community-guide.mdx 中描述的社区协作方式一脉相承Wails 是社区驱动的开源项目可通过开发新功能、修复 bug、测试、撰写文档/教程、在 issues 和 discussions 中帮助他人等多种方式参与。五、常见疑问速查Q我要给 v3 提交一个 bug 修复需要 WEP 吗不需要。已确认的 bug 修复走标准 PR 流程只有新功能、公共 API 或公共行为变更才需要 WEP。Qv3 的 changelog 我要自己写吗默认不需要PR 合并时 v3/scripts/auto-changelog.go 会自动生成条目。想精确控制措辞时可自行向 v3/UNRELEASED_CHANGELOG.md 添加条目。Q我的 v3 PR 标题是chore: bump dependency会被记入 release notes 吗不会。ci/chore/build/test/style类型被判定为内部改动见 v3/scripts/auto-changelog.go 第 381-400 行自动化流程会跳过 changelog 条目。QWEP 被接受了是不是马上就能合并代码不是。接受只是通过提案评审还需要有承诺的实施者完成开发、提交实现 PR、通过评审后才合并之后状态才会更新为Implemented。六、总结Wails 的贡献体系围绕双轨v2 稳定 / v3 beta 分级流程标准 PR / WEP 提案 自动化变更日志三根支柱构建v2 与 v3 源码完全分离变更日志各自独立维护v3 的新功能一律经 WEP 提案Draft PR → 2 周社区讨论 → 维护者裁决 → 编号入册 → 实施合并确保公共行为的每一次演进都有公开的设计依据与可追溯记录自动化脚本则把模型生成与安全净化、去重发布结合起来在提升效率的同时守护 changelog 的数据完整性。无论你贡献的是代码、文档还是测试遵循本指南即可让改动被高效地评审、记录并最终惠及整个 Wails 社区。【免费下载链接】wailsCreate beautiful applications using Go项目地址: https://gitcode.com/gh_mirrors/wa/wails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
