mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
d10d0f544f
A release-readiness QA pass over the whole product. The commits split into defects a user would hit and gates that were reporting green while measuring nothing. ## Fixes that change behaviour Rate limiting was bypassable on every install: TRUST_PROXY defaulted to true, so request.ip came from a client-set header and a forged X-Forwarded-For got past the login limiter. The default is now a private-network trust list. A transient Postgres outage stranded in-flight jobs, leaving finished output on disk with no row pointing at it. A reconciler now resolves those rows and adopts the bytes rather than dropping the work. A Redis connection that moved to a new address wedged every read-blocked consumer, so completions stopped signalling while health still answered 200. Socket timeouts plus subscriber pings recover it. Installing more than one AI bundle left the shared venv multi-versioned and silently broke three tools. The installer now reconciles distributions to one version each. Converting an image to JXL at quality 1 through 4 returned a 500, because libjxl 0.7 rejects the distance those values compute. The quality is floored at what the encoder honours. A missing ffmpeg was also reported to the user as a corrupt upload; it now says the engine is unavailable. RAW uploads reached an unpatched LibRaw on arm64, so it is built from source at 0.22.2, and the release scan was split so it can fail on an unfixed critical instead of hiding it behind ignore-unfixed. ## Gates that could not fail Two mutation lanes ran zero mutants because Stryker crawled the gitignored docs build; coverage discarded its whole report on any failing test; the lint gate skipped root tests, scripts, and two workspaces; and several generated matrices counted a host missing ffmpeg as a passing tool. Each now measures what it claims. Full evidence and the outstanding release items are tracked locally and are not part of this branch.
133 lines
7.7 KiB
Markdown
133 lines
7.7 KiB
Markdown
---
|
|
description: "Cách đóng góp cho SnapOtter. Báo cáo lỗi, yêu cầu tính năng, pull request và các yêu cầu về CLA."
|
|
i18n_source_hash: 6c920a5f83e0
|
|
i18n_provenance: human
|
|
i18n_output_hash: 45552b575bff
|
|
i18n_hash_version: 2
|
|
---
|
|
|
|
# Đóng góp {#contributing}
|
|
|
|
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 {#ways-to-contribute}
|
|
|
|
### Issue (không cần thiết lập gì) {#issues-no-setup-required}
|
|
|
|
- **Báo cáo lỗi** - Có thứ gì đó bị hỏng? Hãy mở một [báo cáo lỗi](https://github.com/snapotter-hq/snapotter/issues/new?template=bug_report.yml) 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](https://github.com/snapotter-hq/snapotter/discussions/new?category=ideas) để 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](https://github.com/snapotter-hq/snapotter/issues/new?template=translation.yml).
|
|
- **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](https://github.com/snapotter-hq/snapotter/issues/new?template=documentation.yml).
|
|
|
|
### Mã nguồn (yêu cầu CLA) {#code-requires-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](/vi/guide/translations)) |
|
|
| 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](https://github.com/snapotter-hq/snapotter/discussions/new?category=ideas) 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](https://github.com/snapotter-hq/snapotter/discussions/new?category=ideas) 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 {#what-we-will-not-accept}
|
|
|
|
- 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](#contributor-license-agreement) đã 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 {#contributor-license-agreement}
|
|
|
|
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](https://github.com/snapotter-hq/snapotter/blob/main/CLA.md) 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ệ contact@snapotter.com để thu xếp một CLA doanh nghiệp trước khi gửi.
|
|
|
|
## Bắt đầu {#getting-started}
|
|
|
|
### Điều kiện tiên quyết {#prerequisites}
|
|
|
|
- Node.js 22.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 {#setup}
|
|
|
|
```bash
|
|
# 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 :1351, API on :13490)
|
|
pnpm dev
|
|
```
|
|
|
|
### Chạy kiểm tra {#running-checks}
|
|
|
|
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ộ:
|
|
|
|
```bash
|
|
pnpm lint # Biome lint + format check
|
|
pnpm typecheck # TypeScript across monorepo
|
|
pnpm test # Vitest unit + integration tests
|
|
```
|
|
|
|
## Quy trình pull request {#pull-request-process}
|
|
|
|
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](https://www.conventionalcommits.org/)
|
|
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 {#review-expectations}
|
|
|
|
- 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 {#after-your-pr-is-merged}
|
|
|
|
Đó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 {#good-first-issues}
|
|
|
|
Đang tìm việc gì đó để làm? Hãy xem [good first issues](https://github.com/snapotter-hq/snapotter/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 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](https://github.com/snapotter-hq/snapotter/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) 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ã {#code-style}
|
|
|
|
- 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](/vi/guide/developer).
|
|
|
|
## Bảo mật {#security}
|
|
|
|
**Đừ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](https://github.com/snapotter-hq/snapotter/security/advisories/new) hoặc email contact@snapotter.com. Xem [SECURITY.md](https://github.com/snapotter-hq/snapotter/blob/main/SECURITY.md) để biết đầy đủ chi tiết.
|
|
|
|
## Câu hỏi? {#questions}
|
|
|
|
- [Tài liệu](https://docs.snapotter.com/)
|
|
- [Discord](https://discord.gg/hr3s7HPUsr)
|
|
- [GitHub Discussions](https://github.com/snapotter-hq/snapotter/discussions)
|