TiddlyWiki5项目代码贡献规范详解

TiddlyWiki5项目代码贡献规范详解

TiddlyWiki5 A self-contained JavaScript wiki for the browser, Node.js, AWS Lambda etc. 项目地址: https://gitcode.com/gh_mirrors/ti/TiddlyWiki5

前言

TiddlyWiki5作为一个开源的个人知识管理工具，其发展离不开社区开发者的共同贡献。本文将详细介绍为TiddlyWiki5项目提交代码变更时需要遵循的各项规范，帮助开发者更好地参与项目协作。

代码提交基本要求

1. 许可要求

所有提交的代码必须满足以下许可条件之一：

• 提交者拥有代码的全部版权
• 代码采用与TiddlyWiki5项目BSD许可证兼容的开源许可证

2. 贡献者协议

每位贡献者必须签署贡献者许可协议(CLA)，这是开源项目的常见要求，确保项目拥有合法使用贡献代码的权利。

3. 提交内容规范

• 每个提交应专注于单一功能变更
• 提交标题需简明扼要(不超过50字符)
• 标题不使用句号结尾
• 采用命令式语气撰写标题(见下文详解)
• 提交说明中需包含充分的变更动机和实现说明
• 提交内容应自包含，不依赖外部资源才能理解
• 涉及界面变更时需提供前后对比截图
• 包含必要的文档更新(用户文档或开发者文档)

命令式标题规范详解

命令式标题是指使用祈使语气，如同给出指令一般。这种规范使提交历史更清晰易读。

优秀标题示例

• "更新贡献指南"
• "将css-escape-polyfill改为$tw.utils方法"
• "使wikitext解析器更易于通过自定义规则集进行子类化"

不佳标题示例

• ~~"编辑文本小部件应使用缺失字段的默认文本"~~
• ~~"签署CLA"~~
• ~~"当options.event缺失时不崩溃"~~

子系统前缀

对于特定子系统的变更，可在标题前添加子系统前缀：

• "菜单插件：在aerial rotator中包含菜单文本"

代码审查规范

TiddlyWiki5项目鼓励开发者参与代码审查，共同提高代码质量。以下是推荐的审查评论规范：

| 评论类型 | 说明 | |---------|------| | 表扬(praise) | 指出代码中的优点，每个审查至少应有一条表扬 | | 细节修正(nitpick) | 指出需要调整的小细节 | | 建议(suggestion) | 提供具体的改进建议 | | 问题(issue) | 指出用户可能遇到的问题 | | 疑问(question) | 提出需要澄清的问题 | | 想法(thought) | 分享审查过程中产生的想法 | | 杂项(chore) | 指出需要完成的小任务 |

贡献者协议签署流程

1. 根据个人或组织身份选择对应的协议文件
2. 在文件末尾添加签名信息，格式为："姓名, @用户名, YYYY/MM/DD"
3. 提交变更请求

开发建议

1. 大型变更前建议先创建咨询议题进行讨论
2. 遵循项目代码风格规范
3. 仔细阅读开发者文档
4. 保持提交的原子性(每个提交只做一件事)

结语

遵循这些规范不仅能提高代码审查效率，也能帮助维护项目的长期健康发展。TiddlyWiki5社区欢迎所有开发者按照这些指南参与贡献，共同打造更好的个人知识管理工具。

TiddlyWiki5 A self-contained JavaScript wiki for the browser, Node.js, AWS Lambda etc. 项目地址: https://gitcode.com/gh_mirrors/ti/TiddlyWiki5