贡献指南

感谢你对 lzt 项目的关注！我们欢迎各种形式的贡献，无论是代码、文档、测试还是反馈建议。

🎯 贡献方式

代码贡献

🐛 修复 Bug
✨ 新增功能
⚡ 性能优化
🔧 代码重构

文档贡献

📝 改进文档
🌍 多语言翻译
📖 教程和示例
🎥 视频教程

测试贡献

🧪 编写单元测试
🔍 集成测试
📊 性能测试
🐛 Bug 报告

社区贡献

💬 回答问题
🎓 技术分享
📢 项目推广
🎨 设计改进

🚀 快速开始

1. 准备开发环境

bash

# 1. Fork 项目到你的 GitHub 账户
# 2. 克隆你的 Fork
git clone https://github.com/your-username/lzt.git
cd lzt

# 3. 添加上游仓库
git remote add upstream https://github.com/FixIterate/lz-stash

# 4. 安装开发依赖
go mod tidy

# 5. 安装开发工具
go install golang.org/x/tools/cmd/goimports@latest
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# 6. 验证环境
go build -o lzt main.go
./lzt --version

2. 文档开发环境

包管理器

本项目使用 Yarn 作为首选的 Node.js 包管理器来管理文档系统，支持 Mermaid 图表渲染。

bash

# 安装文档依赖
yarn install

# 启动文档开发服务器（支持 Mermaid 图表）
yarn docs:dev

# 构建文档（包含 Mermaid 渲染）
yarn docs:build

# 预览构建结果
yarn docs:preview

📋 开发流程

1. 创建特性分支

bash

# 更新主分支
git checkout master
git pull upstream master

# 创建特性分支
git checkout -b feature/your-feature-name
# 或
git checkout -b fix/issue-number

2. 开发和测试

bash

# 运行测试
go test ./...

# 代码格式化
go fmt ./...

# 代码检查
golangci-lint run

# 导入整理
goimports -w .

# 构建验证
go build ./...

3. 提交代码

bash

# 添加更改
git add .

# 提交更改（请遵循提交规范）
git commit -m "feat: add new ledger feature"

# 推送到你的 Fork
git push origin feature/your-feature-name

4. 创建 Pull Request

访问你的 GitHub Fork 页面
点击 "New Pull Request"
选择目标分支为 master
填写 PR 描述（详见 PR 模板）
提交 PR

📁 文件管理规范

依赖文件管理

yarn.lock: 项目使用 yarn.lock 锁定依赖版本，请勿删除或手动修改
package.json: 仅在必要时添加新的依赖项
go.mod/go.sum: Go 模块依赖管理，通过 go mod tidy 维护

提交时的注意事项

bash

# ✅ 正确：提交 yarn.lock 变更
git add yarn.lock package.json

# ❌ 错误：不要提交 node_modules 或临时文件
git add node_modules/  # 请勿提交
git add .DS_Store      # 请勿提交

📝 代码规范

Go 代码风格

我们遵循标准的 Go 代码规范：

// ✅ 良好的函数命名和注释
// Process 处理  交易数据
// 返回处理结果和可能的错误
func Process *Transaction) (*Result, error) {
    if tx == nil {
        return nil, fmt.Errorf("transaction cannot be nil")
    }
    
    // 具体实现...
    return result, nil
}

// ✅ 结构体字段注释
type Transaction struct {
    OrderID      uint      `gorm:"column:order_id;primaryKey" json:"order_id"`           // 订单ID
    Amount       float64   `gorm:"column:amount" json:"amount"`                         // 交易金额
    Type         string    `gorm:"column:type;type:varchar(20)" json:"type"`              // 交易类型
    ErrorReason  string    `gorm:"column:error_reason;type:varchar(128)" json:"error_reason"` // 错误原因
}

命令实现规范

新增命令应遵循现有模式：

// cmd/
package 

import (
    "github.com/spf13/cobra"
    "lzt/cmd"
)

var newCmd = &cobra.Command{
    Use:   "new",
    Short: "简短描述",
    Long:  `详细描述，包含使用场景和示例`,
    Run: func(cmd *cobra.Command, args []string) {
        // 实现逻辑
    },
}

// 参数定义
type newOptions struct {
    concurrency int
    batchSize   int
}

var newOpts = newOptions{}

func init() {
    // 参数绑定
    newCmd.Flags().IntVarP(&newOpts.concurrency, "concurrency", "c", 5, "并发数量")
    
    // 注册到父命令
    cmd.AddCommand(newCmd)
}

Bubble Tea 组件规范

新增 UI 组件应遵循接口规范：

// pkg/bubble/new_component.go
package bubble

import (
    tea "github.com/charmbracelet/bubbletea"
)

// NewComponent 实现 Task 接口的新组件
type NewComponent struct {
    description string
    data        interface{}
}

// Description 实现 Task 接口
func (c *NewComponent) Description() string {
    return c.description
}

// Data 实现 Task 接口
func (c *NewComponent) Data() interface{} {
    return c.data
}

// 处理函数
func processNewComponent(task Task) error {
    // 实现处理逻辑
    return nil
}

🧪 测试要求

单元测试

// internal/app/ledger/domain/entities/transaction_test.go
func TestTransaction_Validate(t *testing.T) {
    tests := []struct {
        name    string
        tx      *Transaction
        wantErr bool
    }{
        {
            name: "valid income transaction",
            tx: &Transaction{
                LedgerID:    1,
                Amount:      100.50,
                Type:        "income",
                Description: "Salary",
            },
            wantErr: false,
        },
        {
            name: "invalid amount",
            tx: &Transaction{
                LedgerID:    1,
                Amount:      -100.0,
                Type:        "income",
            },
            wantErr: true,
        },
        {
            name:    "nil transaction",
            tx:      nil,
            wantErr: true,
        },
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            err := tt.tx.Validate()
            if (err != nil) != tt.wantErr {
                t.Errorf("Validate() error = %v, wantErr %v", err, tt.wantErr)
            }
        })
    }
}

集成测试

// cmd/ledger/init_test.go
func TestInitCommand(t *testing.T) {
    // 设置测试数据库
    db := setupTestDB(t)
    defer teardownTestDB(t, db)
    
    // 运行命令
    cmd := exec.Command("./lzt", "ledger", "init")
    output, err := cmd.CombinedOutput()
    
    // 验证结果
    assert.NoError(t, err)
    assert.Contains(t, string(output), "初始化完成")
}

📦 发布流程

版本号规范

我们使用语义化版本：

v1.0.0 - 主版本：不兼容的 API 修改
v1.1.0 - 次版本：向后兼容的功能性新增
v1.1.1 - 修订版本：向后兼容的问题修正

Git 提交规范

我们使用 Conventional Commits 规范：

bash

# 功能新增
git commit -m "feat: add worker command for concurrent task processing"

# Bug 修复
git commit -m "fix: resolve database connection timeout issue"

# 文档更新
git commit -m "docs: update API documentation with new commands"

# 代码重构
git commit -m "refactor: improve error handling in  module"

# 性能优化
git commit -m "perf: optimize batch processing performance"

# 测试相关
git commit -m "test: add unit tests for transaction model"

# 构建相关
git commit -m "build: update go.mod dependencies"

# CI/CD 相关
git commit -m "ci: add automated testing workflow"

🔍 代码审查

PR 检查清单

提交 PR 前请确保：

[ ] ✅ 代码遵循项目规范
[ ] 🧪 所有测试通过
[ ] 📝 更新相关文档
[ ] 🔍 代码已自我审查
[ ] 📋 填写完整的 PR 描述
[ ] 🏷️ 添加适当的标签

审查要点

审查者将关注：

功能正确性 - 代码是否实现了预期功能
代码质量 - 是否遵循最佳实践
性能影响 - 是否有性能退化
安全性 - 是否存在安全漏洞
可维护性 - 代码是否易于理解和维护
测试覆盖 - 是否有足够的测试

📖 文档贡献

文档结构

docs/
├── index.md              # 首页
├── getting-started/       # 入门指南
│   ├── index.md          # 概览
│   ├── installation.md   # 安装指南
│   └── quick-start.md    # 快速开始
├── api.md                # API 文档
├── design.md             # 架构设计
├── troubleshooting.md    # 故障排除
└── contributing.md       # 贡献指南

文档写作规范

使用清晰、简洁的语言
提供实际可运行的代码示例
包含必要的截图或图表
使用 VitePress 的特性增强可读性

markdown

::: tip 提示
这是一个有用的提示信息。
:::

::: warning 注意
这是需要注意的内容。
:::

::: danger 警告
这是重要的警告信息。
:::

::: code-group
```bash [源码构建]
git clone repo
cd repo
go build

bash

go install package@latest

:::


## 🏷️ Issue 和 PR 模板

### Bug 报告模板

```markdown
## Bug 描述
简要描述遇到的问题。

## 复现步骤
1. 运行命令 `lzt ...`
2. 查看输出
3. 看到错误 '...'

## 期望行为
描述你期望发生的情况。

## 实际行为
描述实际发生的情况。

## 环境信息
- 操作系统: [e.g. macOS 12.0]
- Go 版本: [e.g. 1.24.3]
- lzt 版本: [e.g. v1.3.5]

## 日志输出

粘贴相关的错误日志


## 补充信息
添加任何其他有助于解决问题的信息。

功能请求模板

markdown

## 功能描述
清晰简洁地描述你希望添加的功能。

## 动机和用例
解释为什么需要这个功能，它解决了什么问题。

## 建议的解决方案
描述你希望这个功能如何工作。

## 替代方案
描述你考虑过的其他解决方案。

## 补充信息
添加任何其他相关信息，如设计草图、参考资料等。

🤝 社区行为准则

我们的承诺

为了营造一个开放、友好的环境，我们承诺：

尊重不同的观点和经验
优雅地接受建设性批评
专注于对社区最有利的事情
对社区成员表示同理心

不当行为

以下行为被认为是不当的：

使用性别化语言或图像
人身攻击或政治攻击
公开或私下的骚扰
未经许可发布他人信息

报告途径

如果遇到不当行为，请通过以下方式报告：

发送邮件到 maintainers@example.com
创建私密的 GitHub Issue

🎉 认可贡献者

我们会在以下地方认可所有贡献者：

README.md 的贡献者部分
发布说明中的特别感谢
项目网站的贡献者页面

贡献者类型

👑 维护者 - 项目核心维护团队
💻 代码贡献者 - 提交代码的开发者
📖 文档贡献者 - 改进文档的作者
🐛 Bug 猎手 - 报告重要 Bug 的用户
💡 创意贡献者 - 提供重要建议的用户

📞 联系我们

GitHub Issues: 技术问题和 Bug 报告
GitHub Discussions: 功能讨论和交流
邮件: maintainers@example.com

感谢你的贡献，让我们一起打造更好的 lzt！ 🚀

贡献指南 ​

🎯 贡献方式 ​

代码贡献 ​

文档贡献 ​

测试贡献 ​

社区贡献 ​

🚀 快速开始 ​

1. 准备开发环境 ​

2. 文档开发环境 ​

📋 开发流程 ​

1. 创建特性分支 ​

2. 开发和测试 ​

3. 提交代码 ​

4. 创建 Pull Request ​

📁 文件管理规范 ​

依赖文件管理 ​

提交时的注意事项 ​

📝 代码规范 ​

Go 代码风格 ​

命令实现规范 ​

Bubble Tea 组件规范 ​

🧪 测试要求 ​

单元测试 ​

集成测试 ​

📦 发布流程 ​

版本号规范 ​

Git 提交规范 ​

🔍 代码审查 ​

PR 检查清单 ​

审查要点 ​

📖 文档贡献 ​

文档结构 ​

文档写作规范 ​

功能请求模板 ​

🤝 社区行为准则 ​

我们的承诺 ​

不当行为 ​

报告途径 ​

🎉 认可贡献者 ​

贡献者类型 ​

📞 联系我们 ​

贡献指南

🎯 贡献方式

代码贡献

文档贡献

测试贡献

社区贡献

🚀 快速开始

1. 准备开发环境

2. 文档开发环境

📋 开发流程

1. 创建特性分支

2. 开发和测试

3. 提交代码

4. 创建 Pull Request

📁 文件管理规范

依赖文件管理

提交时的注意事项

📝 代码规范

Go 代码风格

命令实现规范

Bubble Tea 组件规范

🧪 测试要求

单元测试

集成测试

📦 发布流程

版本号规范

Git 提交规范

🔍 代码审查

PR 检查清单

审查要点

📖 文档贡献

文档结构

文档写作规范

功能请求模板

🤝 社区行为准则

我们的承诺

不当行为

报告途径

🎉 认可贡献者

贡献者类型

📞 联系我们