TSone

Contributing

贡献指南

感谢您考虑为 TSone 框架做出贡献。

开发环境设置

克隆仓库

git clone https://github.com/geektech/tsone.git
cd tsone

安装依赖

bun install

运行开发服务器

bun run dev

开发演练项目位于根目录 playground/，官网首页和后台管理页分别由独立 package.json 管理。仓库从 packages/tsone/ 发布框架，从 packages/tsone-cli/ 发布开发 CLI。

构建项目

bun run build

运行代码检查

bun run lint

包边界

  • @geektech/tsone 是浏览器框架，必须保持零外部运行时依赖
  • @geektech/tsone-cli 负责 defineConfig、resolveConfig、startDevServer、build、createProject、tsone create、tsone dev 与 tsone build
  • 不要为 @geektech/tsone 添加 ./dev 导出；应用应单独安装 @geektech/tsone-cli
  • 开发服务器仅提供 HTTP。代理目标可以使用 HTTP 或 HTTPS。
  • 配置文件只支持普通对象默认导出；不支持函数式配置或函数值配置。
  • CLI 首版配置不提供 plugins、WebSocket、HMR、SSR、函数式配置、public/ 复制以及公开的 minify/sourcemap 设置

代码规范

TypeScript

  • 使用 TypeScript 进行开发
  • 遵循项目的 TypeScript 配置
  • 确保类型定义完整

代码风格

  • 遵循项目的 ESLint 配置
  • 使用 Prettier 格式化代码
  • 保持代码风格一致

命名约定

  • 类名使用 PascalCase
  • 函数名和变量名使用 camelCase
  • 常量使用 UPPER_SNAKE_CASE
  • 文件和目录名使用 kebab-case

提交规范

Commit 消息格式

项目使用 Conventional Commits 规范。

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

类型

  • feat: 新功能
  • fix: 修复 bug
  • docs: 文档更新
  • style: 代码风格修改
  • refactor: 代码重构
  • test: 测试相关
  • chore: 构建过程或辅助工具变动

示例

feat(router): 添加路由能力改进

fix(core): 修复响应式系统的内存泄漏问题

docs: 更新组件 API 文档

开发流程

1. 创建分支

git checkout -b feature/your-feature-name

2. 开发功能

  • 实现功能
  • 编写测试
  • 确保代码通过 lint 检查

3. 提交代码

git add .
git commit -m "feat: 描述你的功能"

4. 推送分支

git push origin feature/your-feature-name

5. 创建 Pull Request

  • 前往 GitHub 仓库
  • 点击 New Pull Request
  • 选择你的分支并填写描述

测试

编写测试

bun test
bun test packages/tsone-cli/tests
bunx tsc --noEmit
bun run build
bun pm pack --cwd packages/tsone --dry-run
bun pm pack --cwd packages/tsone-cli --dry-run

测试覆盖

尽量保持高测试覆盖率，确保代码质量。

文档

更新文档

  • 更新 API 文档
  • 更新指南文档
  • 更新示例代码

文档命令

bun run docs
bun run docs:build

文档维护

中文内容维护在 packages/tsone/docs/app/content/zh/，英文内容维护在 packages/tsone/docs/app/content/en/。两边都使用 typed content registry 和结构化 block helper；中英文逻辑路由必须一致。中英文 catalog 当前各包含 17 条逻辑路由；新增或删除路由时必须同步修改两边。

  • 内容链接保持 locale-neutral，不要手写 /en/
  • 中文公开路由不带前缀，英文公开路由使用 /en/
  • 浏览器语言检测仅在 / 生效；手动选择优先并持久化
  • bun run docs:build 遇到缺失、多余、重复、空内容或混用语言的页面时严格失败
  • 托管到子路径时用 bun run docs:build -- --base=/tsone/（或环境变量 DOCS_BASE_PATH）

问题报告

Bug 报告

  • 问题描述
  • 复现步骤
  • 预期行为与实际行为
  • 环境信息和可能的解决方案

功能请求

  • 功能描述
  • 为什么需要这个功能
  • 可能的实现方案

行为准则

  • 尊重他人
  • 接受建设性批评
  • 关注社区的最佳利益
  • 友善和耐心

沟通渠道

  • GitHub Issues: 用于 bug 报告和功能请求
  • GitHub Discussions: 用于讨论和问题解答

许可证

通过贡献代码，您同意你的贡献将在 MIT 许可证下发布。

感谢

再次感谢你的贡献，你的参与将帮助 TSone 变得更好。