Một template Copier khởi tạo dự án Python với uv, ruff, pre-commit, pytest và ty đã cấu hình sẵn, kèm quy trình phát hành theo phiên bản ngữ nghĩa và sinh changelog tự động.
Bạn biết cái cảnh mỗi lần bắt đầu một dự án Python mới, chúng ta lại đi chép các file cấu hình từ dự án trước, chỉnh lại workflow CI/CD, và về cơ bản là phát minh lại cái bánh xe chứ? Đúng rồi, ai cũng từng vậy. Tin vui là những ngày đó đã ở lại phía sau!
Xin giới thiệu Trobz Python Template mới của chúng tôi. Hãy xem nó như bộ dụng cụ khởi đầu cho dự án. Nó được thiết kế để bạn vào việc viết code nhanh hơn và giữ cho mã nguồn của chúng ta nhất quán giữa các dự án. Thêm nữa, nó dùng toàn những công cụ hiện đại mà chúng ta vốn đã quen từ công việc với OCA và Odoo.
Bên trong có gì?
Template được dựng trên Copier, thứ bạn có thể đã gặp khi làm việc với các repo của OCA. Đây là một công cụ dựng khung thông minh: nó hỏi bạn vài câu, và thế là xong — bạn có ngay một dự án Python đã cấu hình đầy đủ, sẵn sàng chạy.
Công cụ hiện đại — những thứ hay ho ta vốn đã biết
Template gồm các công cụ cho việc phát triển Python:
- uv: quản lý gói nhanh như chớp
- ruff: công cụ định dạng và soát lỗi mã nguồn của chúng ta. Bạn hẳn đã thấy nó trong các repo OCA rồi. Nó như một người review code khó tính nhưng hữu ích, và thật sự quan tâm tới sự nhất quán.
- pre-commit: tự động kiểm tra chất lượng mã trước mỗi lần commit
- pytest: cho mọi nhu cầu kiểm thử của bạn.
- ty: công cụ này còn mới và rất hữu ích trong việc tìm ra những lỗi tinh vi trong mã Python của bạn.
Sẵn sàng CI/CD
Khi bật GitHub Actions (nên bật), bạn có:
- Kiểm thử và soát lỗi tự động
- Phát hành tự động: đẩy lên một conventional commit, nó sẽ tăng số phiên bản và xuất bản lên PyPI (nếu đã cấu hình)
- Sinh changelog: tự động cập nhật CHANGELOG.md
Cứ đẩy code lên rồi để đám robot lo phần nhàm chán!
Quy trình đánh phiên bản ngữ nghĩa
Template đi kèm một quy trình đánh phiên bản ngữ nghĩa hoàn toàn tự động, dùng python-semantic-release. Mỗi lần bạn đẩy lên nhánh main (hoặc một PR được merge), quy trình này tự chạy:
- Phân tích các commit của bạn
- Xác định mức tăng phiên bản dựa trên tiêu đề commit
- Cụ thể:
- feat → tăng phiên bản minor (0.1.0 → 0.2.0)
- fix: → tăng phiên bản patch (0.1.0 → 0.1.1)
- feat! hoặc một commit có footer BREAKING CHANGE: → tăng phiên bản major (0.1.0 → 1.0.0)
- Cập nhật phiên bản trong pyproject.toml — bạn không phải tự làm!
- Sinh hoặc cập nhật CHANGELOG.md
- Cập nhật uv.lock — giữ file lock của bạn đồng bộ
- Tạo các file phân phối bằng uv build
- Tạo một Git tag
- Đẩy các thay đổi ngược về repo của bạn
- Tạo một GitHub Release kèm ghi chú phát hành tự sinh
Loại commit và mức tăng phiên bản
Chúng ta theo Conventional Commits, nghĩa là commit của bạn nên trông như thế này:
feat: add user authentication
fix: resolve login timeout issue
docs: update README
Vì sao? Vì CI/CD của chúng ta tự sinh changelog và tự tăng phiên bản dựa trên đó.
Tất cả diễn ra tự động. Bạn chỉ cần viết thông điệp commit cho tử tế!
Lưu ý, những loại commit sau KHÔNG kích hoạt phát hành:
- chore: công việc bảo trì
- ci: thay đổi về CI/CD
- style: định dạng mã
- test: thêm kiểm thử
- docs: cập nhật tài liệu
Mẹo: muốn cố ý bỏ qua GitHub Actions thì thêm tiền tố [skip ci] vào commit.
Xuất bản lên PyPI
Nếu bạn bật thêm publish_to_pypi, quy trình sẽ làm thêm:
- Tải gói của bạn lên PyPI sau mỗi lần phát hành
- Cho phép cài bằng pip install your-package
Việc này đòi thiết lập một trusted publisher cho dự án của bạn, đọc thêm tại đây.
Cấu trúc dự án nhất quán
Mọi dự án đều theo cùng một bố cục:
- pyproject.toml đã cấu hình sẵn với các giá trị mặc định hợp lý
- Makefile với các lệnh thường dùng (make install, make check, make test, v.v.)
- Một .gitignore đầy đủ
- Giấy phép AGPL-3.0 theo mặc định
Bắt đầu thế nào?
1. Tạo một dự án mới
$ copier copy "https://github.com/trobz/trobz-python-template.git" /path/to/your/new/project
2. Cài đặt và thiết lập
$ cd /path/to/your/new/project
# Install everything (creates venv, installs deps, sets up pre-commit)
$ make install
3. Bắt tay vào code!
4. Phát hành ra thế giới
Kết luận
Lần tới khi bắt đầu một dự án Python, hãy thử Trobz Python Template. Nó được thiết kế để tránh đường cho bạn, để bạn tập trung xây những thứ hay ho.
