Đóng Góp cho gac

December 6, 2025 · View on GitHub

Cảm ơn sự quan tâm của bạn trong việc đóng góp cho dự án này! Sự trợ giúp của bạn được đánh giá cao. Vui lòng làm theo các hướng dẫn này để làm cho quy trình suôn sẻ cho mọi người.

Thiết Lập Môi Trường Phát Triển

Dự án này sử dụng uv để quản lý phụ thuộc và cung cấp Makefile cho các tác vụ phát triển phổ biến:

Thiết Lập Nhanh

# Một lệnh để thiết lập mọi thứ bao gồm cả Lefthook hooks
make dev

Lệnh này sẽ:

Cài đặt phụ thuộc phát triển
Cài đặt git hooks
Chạy Lefthook hooks trên tất cả các tệp để sửa bất kỳ vấn đề hiện có nào

Thiết Lập Thay Thể (nếu bạn thích từng bước)

# Tạo môi trường ảo và cài đặt phụ thuộc
make setup

# Cài đặt phụ thuộc phát triển
make dev

# Cài đặt Lefthook hooks
brew install lefthook  # hoặc xem tài liệu dưới đây cho các thay thế
lefthook install
lefthook run pre-commit --all

Các Lệnh Có Sẵn

make setup - Tạo môi trường ảo và cài đặt tất cả phụ thuộc
make dev - Thiết lập phát triển hoàn chỉnh - bao gồm Lefthook hooks
make test - Chạy kiểm thử tiêu chuẩn (loại trừ kiểm thử tích hợp)
make test-integration - Chỉ chạy kiểm thử tích hợp (yêu cầu khóa API)
make test-all - Chạy tất cả kiểm thử
make test-cov - Chạy kiểm thử với báo cáo độ phủ
make lint - Kiểm tra chất lượng mã (ruff, prettier, markdownlint)
make format - Tự động sửa các vấn đề định dạng mã

Tăng Phiên Bản

Quan trọng: PR nên bao gồm việc tăng phiên bản trong src/gac/__version__.py khi chúng chứa các thay đổi nên được phát hành.

Cách Tăng Phiên Bản

Chỉnh sửa src/gac/__version__.py và tăng số phiên bản
Làm theo Semantic Versioning:
- Patch (1.6.X): Sửa lỗi, cải tiến nhỏ
- Minor (1.X.0): Tính năng mới, thay đổi tương thích ngược (ví dụ, thêm nhà cung cấp mới)
- Major (X.0.0): Thay đổi break

Quy Trình Phát Hành

Các bản phát hành được kích hoạt bằng cách đẩy các tag phiên bản:

Hợp nhất PR(s) với tăng phiên bản vào main
Tạo tag: git tag v1.6.1
Đẩy tag: git push origin v1.6.1
GitHub Actions tự động phát hành lên PyPI

Ví dụ:

# src/gac/__version__.py
__version__ = "1.6.1"  # Tăng từ 1.6.0

Sử dụng bump-my-version (tùy chọn)

Nếu bạn đã cài đặt bump-my-version, bạn có thể sử dụng nó tại địa phương:

# Đối với sửa lỗi:
bump-my-version bump patch

# Đối với tính năng mới:
bump-my-version bump minor

# Đối với thay đổi break:
bump-my-version bump major

Tiêu Chuẩn Lập Trình

Target Python 3.10+ (3.10, 3.11, 3.12, 3.13, 3.14)
Sử dụng type hints cho tất cả tham số hàm và giá trị trả về
Giữ mã sạch, gọn và dễ đọc
Tránh sự phức tạp không cần thiết
Sử dụng logging thay vì các câu lệnh print
Định dạng được xử lý bởi ruff (linting, định dạng và sắp xếp import trong một công cụ; độ dài dòng tối đa: 120)
Viết kiểm thử tối thiểu, hiệu quả với pytest

Git Hooks (Lefthook)

Dự án này sử dụng Lefthook để giữ các kiểm tra chất lượng mã nhanh và nhất quán. Các hook được cấu hình phản ánh thiết lập pre-commit trước đây của chúng tôi:

ruff - Linting và định dạng Python (thay thế black, isort và flake8)
markdownlint-cli2 - Linting Markdown
prettier - Định dạng tệp (markdown, yaml, json)
check-upstream - Hook tùy chỉnh để kiểm tra các thay đổi thượng nguồn

Thiết Lập

Cách tiếp cận được đề xuất:

make dev

Thiết lập thủ công (nếu bạn thích từng bước):

Cài đặt Lefthook (lựa chọn tùy chọn phù hợp với thiết lập của bạn):

brew install lefthook          # macOS (Homebrew)
# hoặc
cargo install lefthook         # Rust toolchain
# hoặc
asdf plugin add lefthook && asdf install lefthook latest

Cài đặt các git hooks:
```
lefthook install
```
(Tùy chọn) Chạy trên tất cả các tệp:
```
lefthook run pre-commit --all
```

Các hook bây giờ sẽ chạy tự động trên mỗi commit. Nếu bất kỳ kiểm tra nào thất bại, bạn sẽ cần sửa các vấn đề trước khi commit.

Bỏ Qua Git Hooks

Nếu bạn cần bỏ qua các kiểm tra Lefthook tạm thời, sử dụng flag --no-verify:

git commit --no-verify -m "Thông điệp commit của bạn"

Lưu ý: Chỉ nên sử dụng khi thực sự cần thiết, vì nó bỏ qua các kiểm tra chất lượng mã quan trọng.

Hướng Dẫn Kiểm Thử

Dự án sử dụng pytest để kiểm thử. Khi thêm tính năng mới hoặc sửa lỗi, vui lòng bao gồm các kiểm thử bao gồm các thay đổi của bạn.

Lưu ý rằng thư mục scripts/ chứa các kịch bản kiểm thử cho chức năng không thể dễ dàng kiểm thử với pytest. Cảm thấy tự do thêm các kịch bản ở đây để kiểm tra các kịch bản phức tạp hoặc kiểm thử tích hợp sẽ khó triển khai sử dụng framework pytest tiêu chuẩn.

Chạy Kiểm Thử

# Chạy kiểm thử tiêu chuẩn (loại trừ kiểm thử tích hợp với các cuộc gọi API thực)
make test

# Chỉ chạy kiểm thử tích hợp nhà cung cấp (yêu cầu khóa API)
make test-integration

# Chạy tất cả kiểm thử bao gồm kiểm thử tích hợp nhà cung cấp
make test-all

# Chạy kiểm thử với độ phủ
make test-cov

# Chạy tệp kiểm thử cụ thể
uv run -- pytest tests/test_prompt.py

# Chạy kiểm thử cụ thể
uv run -- pytest tests/test_prompt.py::TestExtractRepositoryContext::test_extract_repository_context_with_docstring

Kiểm Thử Tích Hợp Nhà Cung Cấp

Kiểm thử tích hợp nhà cung cấp thực hiện các cuộc gọi API thực để xác minh rằng các triển khai nhà cung cấp hoạt động chính xác với các API thực tế. Các kiểm thử này được đánh dấu với @pytest.mark.integration và bị bỏ qua theo mặc định để:

Tránh tiêu thụ tín dụng API trong quá trình phát triển thông thường
Ngăn ngừa thất bại kiểm thử khi các khóa API không được cấu hình
Giữ thực hiện kiểm thử nhanh cho việc lặp lại nhanh chóng

Để chạy kiểm thử tích hợp nhà cung cấp:

Thiết lập khóa API cho các nhà cung cấp bạn muốn kiểm thử:

export ANTHROPIC_API_KEY="your-key"
export CEREBRAS_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export GROQ_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export OPENROUTER_API_KEY="your-key"
export STREAMLAKE_API_KEY="your-key"
export ZAI_API_KEY="your-key"
# LM Studio và Ollama yêu cầu một phiên bản địa phương đang chạy
# Khóa API cho LM Studio và Ollama là tùy chọn trừ khi triển khai của bạn thực thi xác thực

Chạy kiểm thử nhà cung cấp:
```
make test-integration
```

Kiểm thử sẽ bỏ qua các nhà cung cấp nơi các khóa API không được cấu hình. Các kiểm thử này giúp phát hiện các thay đổi API sớm và đảm bảo tương thích với các API nhà cung cấp.

Đối với xử lý sự cố, xem TROUBLESHOOTING.md
Đối với việc sử dụng và các tùy chọn CLI, xem USAGE.md
Đối với chi tiết giấy phép, xem ../../LICENSE

Cảm ơn đã giúp cải thiện gac!