Hướng dẫn đóng góp

Bắt đầu

Bước 1: Phân nhánh kho lưu trữ và sao chép nó vào máy cục bộ của bạn

# Clone the repository from your fork
git clone https://github.com/xxxxx/read-frog.git

# Enter the project directory
cd read-frog

# Add the upstream remote to sync with the original repository
git remote add upstream https://github.com/mengxi-ream/read-frog.git

Bước 2: Cài đặt các phụ thuộc và bắt đầu phát triển

# Install dependencies
pnpm i

# Start the development server
pnpm dev

Điều này sẽ bắt đầu môi trường phát triển phần mở rộng. Tiện ích mở rộng sẽ tự động mở trong trình duyệt mặc định của bạn.

Mẹo phát triển

Sử dụng npx với pnpm Node.js Quản lý

Chúng tôi đang sử dụng tính năng quản lý phiên bản Node.js tích hợp sẵn của pnpm (được giới thiệu trong pnpm 10.14). Bạn có thể gặp lỗi EBADDEVENGINES khi chạy lệnh npx. Có hai giải pháp:

Giải pháp 1: Sử dụng pnpm dlx hoặc pnpx thay vì npx

# Instead of npx
npx some-package@latest

# Use pnpm dlx
pnpm dlx some-package@latest

# Or use pnpx (alias for pnpm dlx)
pnpx some-package@latest

Giải pháp 2: Căn chỉnh phiên bản Node.js với pnpm

Khi không thuận tiện để thay thế npx (ví dụ: đối với các bản cài đặt MCP trong phạm vi người dùng trong Claude Code), hãy căn chỉnh phiên bản Node.js của bạn:

# Install and use the required Node.js version globally
pnpm env use --global 22.18.0

Mở tiện ích mở rộng trong trình duyệt cụ thể

Bạn có thể tạo/modify tệp web-ext.config.ts trong thư mục gốc để chỉ định rõ ràng đường dẫn trình duyệt.

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  binaries: {
      chrome: "path/to/your/chrome.exe",
      firefox: "path/to/your/firefox.exe",
      edge: "path/to/your/edge.exe"
    }
});

Nhà phát triển pnpm không thể tự động tải tiện ích mở rộng

Nếu bạn sử dụng Chrome phiên bản 137 trở lên, bạn cần tải xuống Chrome for Testing để phát triển. Xem details.

Cấu hình Chrome liên tục

Theo mặc định, web-ext tạo hồ sơ mới mỗi khi bạn chạy tập lệnh nhà phát triển.

Nếu bạn muốn giữ thông tin đăng nhập, tiện ích mở rộng công cụ phát triển và cài đặt trình duyệt giữa các phiên phát triển, hãy tạo hoặc cập nhật web-ext.config.ts trong thư mục gốc của dự án.

Cấu hình hồ sơ liên tục hơi khác nhau giữa các hệ điều hành:

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  chromiumArgs: ['--user-data-dir=./.wxt/chrome-data'],
});

Trên Windows, WXT khuyên bạn nên sử dụng chromiumProfile và keepProfileChanges. Đường dẫn chromiumProfile phải tuyệt đối, vì vậy hãy sử dụng resolve từ node:path.

Lợi ích: Hồ sơ của bạn vẫn tồn tại giữa các phiên phát triển, vì vậy bạn có thể:

• Cài đặt tiện ích mở rộng devtools
• Ghi nhớ thông tin đăng nhập
• Giữ cài đặt trình duyệt

💡 Mẹo: Cấu hình liên tục chỉ áp dụng cho trình duyệt Chrome. Bạn có thể thay thế .wxt/chrome-data trong các ví dụ để sử dụng thư mục hồ sơ riêng cho từng dự án.

Sự cố đăng nhập Google ở Chế độ nhà phát triển

Nếu bạn muốn đăng nhập bằng tài khoản Google ở chế độ nhà phát triển và gặp lỗi "Trình duyệt hoặc ứng dụng này có thể không an toàn.", bạn cần tắt tính năng phát hiện tự động hóa.

Giải pháp: Thêm chromiumArgs vào web-ext.config.ts của bạn:

// web-ext.config.ts
import { defineWebExtConfig } from 'wxt';

export default defineWebExtConfig({
  chromiumArgs: ['--disable-blink-features=AutomationControlled'],
});

Điều này vô hiệu hóa tính năng phát hiện tự động hóa khiến Google chặn các nỗ lực đăng nhập từ các trình duyệt tự động.

Sự cố gỡ lỗi điểm dừng

⚠️ Nếu bạn gặp sự cố khi gỡ lỗi điểm dừng, có thể là do cài đặt danh sách bỏ qua của Chrome DevTools. Các tập lệnh nội dung do tiện ích mở rộng đưa vào có thể tự động bị bỏ qua, khiến điểm dừng không thành công.

Giải pháp:

1. Mở DevTools trên bất kỳ trang web nào
2. Nhấp vào biểu tượng cài đặt (⚙️) ở góc trên cùng bên phải
3. Chọn "Bỏ qua danh sách" từ điều hướng bên trái
4. Đảm bảo **không chọn tùy chọn "Tập lệnh nội dung được tiện ích mở rộng chèn vào"

macOS: Lỗi quá nhiều tệp đang mở (EMFILE)

Nếu bạn gặp lỗi này trên macOS khi chạy pnpm dev:

Điều này xảy ra vì Chokidar (thư viện xem tệp được Vite/WXT) sử dụng mặc định sử dụng FSEvents gốc của macOS, vốn yêu cầu bộ mô tả tệp cho mỗi tệp đã xem/directory. Các dự án lớn có thể vượt quá giới hạn hệ thống.

Giải pháp: Đặt CHOKIDAR_USEPOLLING=true để chuyển sang chế độ thăm dò ý kiến, chế độ này không yêu cầu bộ mô tả tệp.

Tạo hoặc cập nhật tệp .env trong thư mục gốc của dự án:

# .env
CHOKIDAR_USEPOLLING=true

Sau đó, pnpm dev sẽ hoạt động mà không gặp lỗi EMFILE.

Lưu ý: Chế độ thăm dò chậm hơn một chút và sử dụng nhiều CPU hơn nhưng tránh được vấn đề giới hạn bộ mô tả tệp.

Gửi mã

Tạo một chi nhánh mới

# For new features
git checkout -b feat/the-feature

# For bug fixes
git checkout -b fix/the-bug

# For docs modify
git checkout -b docs/the-docs

Hợp nhất chi nhánh

Nếu nhánh chính từ xa được cập nhật và tạo ra xung đột trong PR của chúng tôi, bạn có thể giải quyết bằng cách hợp nhất nhánh từ xa trước .

# Switch to the main branch
git checkout main

# Pull the latest code from upstream
git pull upstream main

# Switch back to your local branch
git checkout docs/xxxx

# Merge the main branch into your local branch
git rebase main

# Push the code again if there are conflicts after rebase
git push --force-with-lease origin docs/xxxx

# If there are no conflicts, push the code again
git push origin docs/xxxx

fatal: 'upstream' does not appear to be a git repository
fatal: Could not read from remote repository.

git remote add upstream https://github.com/mengxi-ream/read-frog.git

Tạo yêu cầu kéo

Trước khi tạo Yêu cầu kéo, bạn cần thêm bộ thay đổi để ghi lại các thay đổi của mình.

Hiểu các lỗi phiên bản

Chọn loại vết sưng phiên bản thích hợp dựa trên những thay đổi của bạn:

• patch - Sửa lỗi, lỗi chính tả, cập nhật tài liệu, cải tiến nhỏ
  • Ví dụ: Sửa lỗi dịch, cập nhật README, sửa kiểu nút, cải thiện hiệu suất
• nhỏ - Các tính năng mới tương thích ngược
  • Ví dụ: Thêm nút tắt dịch, thêm tính năng xuất từ vựng
• chính - Những thay đổi lớn ảnh hưởng đến chức năng hiện có
  • Ví dụ: Thay đổi cấu trúc API, xóa các tính năng không được dùng nữa, tái cấu trúc chính

Thêm một bộ thay đổi

# Run the changeset command
pnpm changeset

# 1. Choose version bump type for each selected package
🦋  What kind of change is this for @read-frog/extension? (current version is 1.17.3)
❯ patch   # For bug fixes and minor improvements
  minor   # For new features
  major   # For breaking changes

# 2. Write a summary of your changes
🦋  Please enter a summary for this change (this will be in the changelog)
Summary >>> fix: translation button style

Sau khi chạy pnpm changeset, một tệp đánh dấu sẽ được tạo trong thư mục .changeset. Bạn có thể chỉnh sửa tệp này để cung cấp thêm chi tiết về các thay đổi của mình trước khi tạo Yêu cầu kéo.

Sau đó tạo Yêu cầu kéo và đợi nó được hợp nhất.

Công ước cam kết

Chúng tôi sử dụng đặc tả Conventional Commits để viết thông báo cam kết.

Đặt biến môi trường

Để tự động tải các biến môi trường trong khi phát triển tiện ích mở rộng, chẳng hạn như khóa API cho môi trường phát triển, bạn có thể tạo tệp .env.development trong thư mục gốc.

# .env.development
WXT_OPENAI_API_KEY=xxx
WXT_DEEPSEEK_API_KEY=xxx

WXT tải các tệp dotenv theo quy ước Vite. Các biến cần được truy cập từ mã mở rộng thông qua import.meta.env nên sử dụng tiền tố WXT_.

Nếu bạn chỉ cần đặt một biến môi trường cho một lệnh duy nhất, cú pháp sẽ phụ thuộc vào shell của bạn:

SKIP_FREE_API=true pnpm test

Các shell Windows mặc định không hỗ trợ cú pháp macOS/Linux KEY=value command. Nếu lệnh không thành công vì lý do đó, hãy sử dụng biểu mẫu PowerShell hoặc CMD ở trên. Đối với các biến WXT mà bạn sử dụng thường xuyên, hãy đặt chúng vào .env.development.

Bỏ qua các bài kiểm tra Google API ở Trung Quốc

Nếu bạn là cộng tác viên từ Trung Quốc đại lục, khi cần đẩy mã, hãy sử dụng lệnh sau:

SKIP_FREE_API=true git push

Tại sao điều này là cần thiết? Bởi vì việc kiểm tra mã được thực hiện trong quá trình đẩy, nhưng API miễn phí của Google không thể truy cập được ở Trung Quốc đại lục. Điều này sẽ khiến các thử nghiệm thất bại và việc đẩy bị từ chối. Bằng cách đặt biến môi trường SKIP_FREE_API, chúng tôi bỏ qua các bài kiểm tra của Google.

Những loại PR nào sẽ được xem xét và sáp nhập?

Bắt đầu với sự đóng góp

Nếu đây là một trong những PR đầu tiên của bạn và bạn nghiêm túc trong việc đóng góp thì thông thường nó sẽ không bị từ chối do vấn đề chất lượng. Người bảo trì sẽ giúp bạn xác định vấn đề và điều chỉnh cho phù hợp với quy trình phát triển cũng như kiểu mã của chúng tôi. Tuy nhiên, chúng tôi thực sự khuyên bạn nên làm theo các nguyên tắc sau:

1. Bắt đầu với những vấn đề nhỏ, chẳng hạn như "Vấn đề đầu tiên tốt" trong kho lưu trữ. Các PR nhỏ, đơn giản mang lại một quá trình học tập suôn sẻ.
2. Đảm bảo PR của bạn vượt qua tất cả các hành động GitHub và các bài kiểm tra cục bộ.

Tại sao PR của tôi không được các nhà bảo trì xem xét?

1. Bạn đã đóng góp một PR quá phức tạp trước khi làm quen với cơ sở mã, dẫn đến có quá nhiều thay đổi bắt buộc.
2. Mã của bạn chứa nhiều lỗi cơ bản, khiến người bảo trì đặt câu hỏi về mức độ nghiêm trọng của bạn:
   • Các đoạn mã không được sử dụng chưa bị xóa
   • Mã lặp lại quá mức
   • Tên biến và hàm quá tùy tiện
   • Chúng tôi khuyến khích sự phát triển có sự hỗ trợ của AI, nhưng bạn đã không xem xét cẩn thận mã do AI tạo ra, dẫn đến mã có chất lượng thấp, không thể duy trì hoặc được thiết kế quá mức
3. Người bảo trì đã cung cấp đề xuất sửa đổi nhiều lần nhưng bạn không làm theo hoặc những thay đổi của bạn không giải quyết được vấn đề gốc.