Đóng góp

Cảm ơn bạn đã quan tâm đến việc đóng góp. Hướng dẫn này trình bày cách tham gia, những gì chúng tôi chấp nhận, và cách bắt đầu.

Các cách đóng góp

Issue (không cần thiết lập gì)

• Báo cáo lỗi - Có thứ gì đó bị hỏng? Hãy mở một báo cáo lỗi kèm các bước tái hiện.
• Yêu cầu tính năng - Bạn có ý tưởng? Hãy bắt đầu một thảo luận để cộng đồng cân nhắc và bình chọn cho nó.
• Vấn đề về bản dịch - Phát hiện một bản dịch sai hoặc thiếu? Hãy mở một issue về bản dịch.
• Vấn đề về tài liệu - Có gì đó không ổn trong tài liệu? Hãy mở một issue về tài liệu.

Mã nguồn (yêu cầu CLA)

Chúng tôi chấp nhận pull request cho:

Loại	Quy trình
Sửa lỗi	Mở PR trực tiếp (liên kết tới issue nếu có)
Bản dịch mới	Mở PR trực tiếp (xem Hướng dẫn dịch)
Cải thiện tài liệu	Mở PR trực tiếp
Cải thiện độ bao phủ kiểm thử	Mở PR trực tiếp
Công cụ hoặc tính năng mới	Bắt đầu một thảo luận trước; một maintainer sẽ chuyển các ý tưởng đã được phê duyệt thành issue được theo dõi trước khi bạn viết mã
Refactor hoặc thay đổi kiến trúc	Bắt đầu một thảo luận trước và chờ maintainer chấp thuận trước khi viết mã

Những gì chúng tôi sẽ không chấp nhận

• Thay đổi đối với các workflow CI/CD, cấu hình phát hành, hoặc cấu hình linter/compiler
• PR mà không có Thỏa thuận Giấy phép Người đóng góp đã ký
• PR thay đổi hơn 400 dòng (hãy chia công việc lớn thành các PR nhỏ hơn)
• Tính năng chưa được thảo luận và phê duyệt trước
• Thay đổi đối với packages/ai/ mà không thảo luận trước

Thỏa thuận Giấy phép Người đóng góp

Trước khi chúng tôi có thể hợp nhất PR đầu tiên của bạn, bạn phải ký CLA cá nhân của chúng tôi. Đây là yêu cầu chỉ một lần.

Tại sao: SnapOtter cấp phép kép (AGPLv3 + thương mại). CLA trao cho chúng tôi quyền phân phối các đóng góp của bạn theo cả hai giấy phép. Bạn giữ toàn bộ quyền sở hữu bản quyền đối với công việc của mình.

Bằng cách nào: Khi bạn mở PR đầu tiên, bot CLA Assistant sẽ để lại bình luận kèm một liên kết. Nhấp vào đó, xem lại thỏa thuận, và ký bằng tài khoản GitHub của bạn. Chỉ mất 30 giây.

Nếu bạn đóng góp thay mặt cho nhà tuyển dụng của mình và nhà tuyển dụng giữ quyền sở hữu trí tuệ đối với công việc của bạn, hãy liên hệ [email protected] để thu xếp một CLA doanh nghiệp trước khi gửi.

Bắt đầu

Điều kiện tiên quyết

• Node.js 22+
• pnpm 9+
• Python 3.11+ (chỉ dành cho các công cụ AI)
• Docker (tùy chọn, để kiểm thử tích hợp đầy đủ)

Thiết lập

# Fork and clone
git clone https://github.com/<your-username>/snapotter.git
cd snapotter

# Start Postgres + Redis for local dev
docker compose -f docker-compose.dev.yml up -d

# Install dependencies
pnpm install

# Start dev servers (web on :1349, API on :13490)
pnpm dev

Chạy kiểm tra

Trước khi gửi PR, hãy đảm bảo tất cả các kiểm tra đều vượt qua ở máy cục bộ:

pnpm lint          # Biome lint + format check
pnpm typecheck     # TypeScript across monorepo
pnpm test          # Vitest unit + integration tests

Quy trình pull request

1. Fork repo và tạo một nhánh từ main (feat/my-feature hoặc fix/issue-123)
2. Thực hiện các thay đổi trong những commit tập trung, dễ xem xét bằng conventional commits
3. Thêm hoặc cập nhật kiểm thử cho các thay đổi của bạn
4. Chạy pnpm lint && pnpm typecheck && pnpm test ở máy cục bộ
5. Mở PR nhắm vào main và điền vào mẫu
6. Ký CLA nếu được nhắc
7. Chờ CI vượt qua và một maintainer xem xét

Kỳ vọng về việc xem xét

• Chúng tôi cố gắng phản hồi PR trong vòng 7 ngày
• PR nhỏ, tập trung sẽ được xem xét nhanh hơn
• Nếu bạn không nhận được phản hồi trong 7 ngày, hãy để lại bình luận nhắc trong luồng
• Chúng tôi có thể yêu cầu thay đổi, đề xuất một cách tiếp cận khác, hoặc đóng PR nếu nó không phù hợp với định hướng dự án

Sau khi PR của bạn được hợp nhất

Đóng góp của bạn sẽ được đưa vào bản phát hành tiếp theo và được ghi công trong changelog.

Good first issues

Đang tìm việc gì đó để làm? Hãy xem good first issues của chúng tôi để tìm các nhiệm vụ thân thiện với người mới, hoặc help wanted cho những hạng mục lớn hơn nơi chúng tôi rất mong nhận được sự trợ giúp của cộng đồng.

Phong cách mã

• Biome xử lý định dạng và linting (dấu nháy kép, dấu chấm phẩy, thụt lề 2 khoảng trắng)
• Hook trước khi commit tự động chạy biome check --write trên các tệp đã được staged
• Nếu linter phàn nàn, hãy sửa mã (đừng chỉnh sửa cấu hình Biome)
• ES module ở khắp mọi nơi (import/export)
• Conventional commits: feat:, fix:, refactor:, docs:, test:, chore:

Để biết đầy đủ chi tiết kiến trúc, hãy xem Hướng dẫn dành cho nhà phát triển.

Bảo mật

Đừng mở PR hoặc issue công khai cho các lỗ hổng bảo mật. Hãy báo cáo chúng một cách riêng tư qua GitHub Security Advisories hoặc email [email protected]. Xem SECURITY.md để biết đầy đủ chi tiết.

Câu hỏi?

• Tài liệu
• Discord
• GitHub Discussions