Skip to content

CONTRIBUTING.zh-CN.md

Latest commit

 

History

History
207 lines (137 loc) · 5.51 KB

CONTRIBUTING.zh-CN.md

File metadata and controls

207 lines (137 loc) · 5.51 KB
Raw

贡献说明

English

感谢你为 Kun 做贡献。

这份文档说明了贡献者应该如何协作、遵循什么标准，以及改动应如何提交。

项目品味

代码不难，难得的是好品味。

在 Kun 里，品味意味着清晰的流程、克制的界面、自然的文案，以及用一次就能理解的行为。好的贡献不只是把功能做出来，也要体现判断力。

贡献范围

欢迎以下方向的贡献：

  • 缺陷修复
  • UI / UX 优化
  • 运行时集成改进
  • 文档补充与修订
  • 本地化内容完善
  • 构建和发布流程优化

分支策略

建议采用以下分支流转方式：

  • develop：协作与日常集成分支
  • master：稳定发布分支，由维护者从 develop 合入
  • 功能分支：可选，从 develop 拉出的短期分支

规则如下：

  • 不要直接在 master 上开发
  • 日常开发优先从最新 develop 开始
  • 如果要建立功能分支，应从 develop 拉出
  • 除非维护者明确指定，否则 PR 默认提到 develop

开始之前

  1. 先确保本地仓库已同步到最新状态。
  2. 切换到 develop 分支。
  3. 运行 npm install 安装依赖。
  4. 在修改前先确认项目可以正常启动或构建。

典型 PR 的结构

一个结构良好的 Kun PR 应该聚焦且自包含。通常：

  • 涉及 1-3 个新文件，修改 2-5 个现有文件进行接入
  • 范围限定在单个功能、修复或文档更新
  • 如果界面有变化，附带视频或 GIF
  • 如果项目逻辑有变化，附带单元测试
  • 通过 npm run typecheck、npm run build 和 npm run test

如果在开发过程中发现其他需要处理的问题，请单独开 issue，不要扩大当前 PR 的范围。

本地开发检查清单

在发起 PR 之前，贡献者应至少确认：

  • 应用可通过 npm run dev 正常开发运行
  • npm run typecheck 通过
  • npm run build 通过
  • npm run test 通过
  • UI 改动已附带展示变更流程的视频或 GIF
  • 逻辑改动已为变更行为补充单元测试
  • 如果改动影响使用方式、安装方式或流程，已同步更新文档
  • 如果改动影响用户可见文案，已同步更新本地化内容

CI 验证命令

# 类型检查
npm run typecheck

# 生产构建
npm run build

# 单元测试
npm run test

# 完整开发冒烟测试
npm run dev

代码要求

  • 改动尽量聚焦、范围清晰
  • 不要在同一个 PR 里夹带无关重构
  • 尽量遵循现有项目结构和命名方式
  • 优先写易读、易维护的代码
  • 尽量保持跨平台行为一致
  • 不要提交密钥、Token、API Key 或带有隐私的机器本地路径

文档要求

当你的改动会影响项目使用方式或协作方式时，请同步更新相关文档：

  • README.md 和 README.en.md：项目级说明
  • docs/DEVELOPMENT.md 和 docs/DEVELOPMENT.zh-CN.md：开发流程与协作规范
  • 当前这份贡献说明：当贡献标准发生变化时更新

Pull Request 标准

每个 PR 应尽量满足：

  • 标题清晰、具体
  • 说明改了什么以及为什么改
  • 写清楚用户侧会受到什么影响
  • 如有安装、迁移、兼容性注意事项，应明确说明
  • 规模尽量可控，方便评审

推荐 PR 描述结构：

## Summary

用一两句话说明这个 PR 做了什么。

## Why

要解决的问题或填补的空白。

## Validation

如何验证改动（执行的命令、手动测试步骤）。

## Media

如果界面有变化，附上视频或 GIF。截图可以作为补充材料。

## Tests

如果项目逻辑有变化，列出新增或更新的单元测试。

对于大多数贡献，建议从短期功能分支发起 PR，而不是直接向 develop 或 master 推送提交。

评审标准

评审时建议重点关注：

  • 正确性
  • 是否引入回归
  • 产品品味与交互质量
  • 可读性与可维护性
  • 是否符合当前架构方向
  • 文档是否同步完整
  • 校验步骤是否真实执行

Commit 建议

好的 Commit 应该：

  • 颗粒度适中，便于审阅
  • 按逻辑分组
  • 提交信息清晰明确

遵循 conventional commits 规范：

  • feat: 新功能
  • fix: 缺陷修复
  • docs: 文档变更
  • refactor: 代码重构
  • style: 格式化、界面调整
  • chore: 维护任务

示例：

  • docs: rewrite README and contribution guides
  • feat: improve runtime connection recovery
  • fix: handle missing Kun binary path

提交 Issue

提交 Issue 时，请尽可能包含以下信息：

  • 操作系统及版本
  • Kun 版本（可在设置页或关于对话框查看）
  • 内置的 kun 版本（如可用，在同目录下执行 kun --version）
  • 复现步骤
  • 预期行为与实际行为
  • 相关错误信息、日志或截图

贡献者协作方式

请以以下方式协作：

  • 尊重他人
  • 表达清晰
  • 反馈建设性
  • 愿意讨论与调整

如果改动范围较大或风险较高，建议先和维护者对齐方向，再投入较多实现成本。

需要帮助？

如果需求或边界不明确，先沟通确认，再进行较大范围的架构或流程调整。如有任何关于贡献的问题，欢迎提 Issue。

许可证

外部贡献基于英文 Contributor License Agreement 接收。提交贡献即表示你同意 CLA 中的授权条款，包括项目所有者可将你的贡献作为 Kun 的一部分进行再授权、商业授权或其他形式授权。

项目本身默认仍基于 PolyForm Noncommercial License 1.0.0 发布；除非项目所有者另行提供书面商业授权。