Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
268 lines (181 loc) · 6.74 KB

CONTRIBUTING.md

File metadata and controls

268 lines (181 loc) · 6.74 KB

Contributing to encoding | 贡献指南

Thank you for your interest in contributing to this project! 感谢你对本项目的关注！

Table of Contents | 目录

Prerequisites | 前置要求

Before you begin, ensure you have the following tools installed:

开始之前，请确保已安装以下工具：

Required | 必需

  • C++ Compiler: g++ 9+ or clang++ 10+ (with C++17 support)
  • Go: 1.19 or later
  • Rust: 1.70 or later (with rustfmt and clippy)
  • Python: 3.8 or later (for benchmark scripts)

Optional | 可选

  • Make: For simplified build commands
  • Docker: For consistent build environment

Installation Examples | 安装示例

Ubuntu/Debian:

sudo apt update
sudo apt install g++ golang rustc python3

macOS (with Homebrew):

brew install gcc go rust python3

Windows:

Development Setup | 开发环境配置

  1. Fork and clone the repository | Fork 并克隆仓库
git clone https://github.com/LessUp/compress-kit.git
cd compress-kit
  1. Verify your environment | 验证环境
# Check C++ compiler
g++ --version

# Check Go
go version

# Check Rust
rustc --version
cargo --version

# Check Python
python3 --version
  1. Build all implementations | 构建所有实现
# C++ (example: Huffman)
cd algorithms/huffman/cpp && g++ -std=c++17 -O2 main.cpp -o huffman_cpp && cd ../..

# Go (example: Huffman)
cd algorithms/huffman/go && go build -o huffman_go . && cd ../..

# Rust (example: Huffman)
cd algorithms/huffman/rust && rustc -O main.rs -o huffman_rust && cd ../..

Code Style | 代码风格

C++

  • Follow Google C++ Style Guide
  • Use 4 spaces for indentation
  • Use snake_case for functions and variables
  • Use PascalCase for classes and structs
# Format check (if clang-format is available)
clang-format --dry-run --Werror *.cpp

Go

  • Use gofmt for formatting (mandatory)
  • Use go vet for static analysis
  • Follow Effective Go
# Format code
gofmt -w .

# Check for issues
go vet ./...

Rust

# Format code
cargo fmt

# Lint code
cargo clippy -- -D warnings

Python

  • Follow PEP 8
  • Use 4 spaces for indentation

Testing | 测试

Running Benchmarks | 运行基准测试

# Generate test data
python3 tests/gen_testdata.py

# Run all benchmarks
python3 scripts/run_all_bench.py

# Run specific algorithm benchmark
cd algorithms/huffman/benchmark && python3 bench.py
cd algorithms/rle/benchmark && python3 bench.py

Verifying Correctness | 验证正确性

Each implementation should pass the encode-decode round-trip test:

每个实现都应通过编码-解码往返测试：

# Example: Huffman C++
./huffman_cpp encode input.bin encoded.huf
./huffman_cpp decode encoded.huf decoded.bin
diff input.bin decoded.bin  # Should produce no output

Cross-Language Verification | 跨语言验证

Files encoded by one language implementation should be decodable by others:

一种语言编码的文件应能被其他语言正确解码：

# Encode with C++, decode with Go
./huffman_cpp encode input.bin encoded.huf
./huffman_go decode encoded.huf decoded.bin
diff input.bin decoded.bin

Spec-Driven Development | 规范驱动开发

This project follows Spec-Driven Development (SDD). All code implementations must be based on the specification documents in /specs/.

本项目遵循规范驱动开发（SDD）。所有代码实现必须以 /specs/ 目录下的规范文档为依据。

Workflow | 工作流

  1. Review Specs First | 先审查规范: Before writing any code, read the relevant documents in /specs/product/, /specs/rfc/, or /specs/testing/.

    编写代码前，请先阅读 /specs/product/、/specs/rfc/ 或 /specs/testing/ 中的相关文档。

  2. Update Specs First | 先更新规范: For new features or interface changes, propose spec changes first. Wait for confirmation before coding.

    对于新功能或接口变更，请先提议更新规范文档，确认后再编写代码。

  3. Implement to Spec | 按规范实现: Code must 100% adhere to spec definitions (naming, API paths, data types, etc.).

    代码必须 100% 遵守规范定义（命名、API 路径、数据类型等）。

  4. Test Against Spec | 按规范测试: Write tests based on the acceptance criteria in /specs/.

    根据 /specs/ 中的验收标准编写测试。

See AGENTS.md for the complete AI workflow instructions.

完整的 AI 工作流指令，请参阅 AGENTS.md。

Pull Request Process | PR 流程

  1. Create a feature branch | 创建功能分支
git checkout -b feature/your-feature-name
  1. Make your changes | 进行修改
  • Write clean, readable code
  • Add comments for complex logic
  • Update documentation if needed
  1. Test your changes | 测试修改
# Build and test
# Run benchmarks to verify correctness
  1. Commit with clear messages | 提交清晰的 commit 信息
git commit -m "feat: add XXX feature"
# or
git commit -m "fix: resolve XXX issue"

Commit message format | 提交信息格式:

  • feat: New feature | 新功能
  • fix: Bug fix | 修复 bug
  • docs: Documentation | 文档
  • style: Code style | 代码风格
  • refactor: Refactoring | 重构
  • test: Tests | 测试
  • chore: Maintenance | 维护
  1. Push and create PR | 推送并创建 PR
git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

  1. PR Checklist | PR 检查清单

Before submitting, ensure:

提交前请确保：

  • Code compiles without errors | 代码编译无错误
  • All tests pass | 所有测试通过
  • Code follows the style guide | 代码符合风格指南
  • Documentation is updated | 文档已更新
  • CHANGELOG.md is updated (if applicable) | CHANGELOG 已更新（如适用）

Questions? | 有问题？

Feel free to open an issue if you have any questions or suggestions!

如有任何问题或建议，欢迎提交 Issue！