Read Frog

기여 가이드

더 나은 언어 학습 제품을 함께 만들어 봅시다

시작하기

1단계: 리포지토리를 포크하고 로컬 머신에 복제

# 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

2단계: 종속성 설치 및 개발 시작

# Install dependencies
pnpm i

# Start the development server
pnpm dev

그러면 확장 개발 환경이 시작됩니다. 확장 프로그램은 기본 브라우저에서 자동으로 열립니다.

개발 팁

pnpm Node.js 관리와 함께 npx 사용

우리는 pnpm에 내장된 Node.js 버전 관리(pnpm 10.14에 도입됨)를 사용하고 있습니다. npx 명령을 실행할 때 EBADDEVENGINES 오류가 발생할 수 있습니다. 두 가지 솔루션이 있습니다.

해결책 1: npx 대신 pnpm dlx 또는 pnpx 사용

# 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

해결책 2: Node.js 버전을 pnpm과 일치시키세요

npx을 교체하는 것이 편리하지 않은 경우(예: Claude Code에 사용자 범위 MCP 설치의 경우) Node.js 버전을 조정하세요.

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

특정 브라우저에서 확장 프로그램 열기

루트 디렉터리에 /modify web-ext.config.ts 파일을 생성하여 브라우저 경로를 명시적으로 지정할 수 있습니다.

// 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"
    }
});

pnpm 개발자가 확장 프로그램을 자동으로 로드할 수 없습니다.

Chrome 버전 137 이상을 사용하는 경우 개발을 위해 Chrome for Testing을 다운로드해야 합니다. details을 참조하세요.

영구 Chrome 프로필

기본적으로 web-ext는 개발 스크립트를 실행할 때마다 새 프로필을 생성합니다.

개발 세션 간에 로그인, devtools 확장 및 브라우저 설정을 유지하려면 프로젝트 루트에서 web-ext.config.ts을 생성하거나 업데이트하세요.

영구 프로필 구성은 운영 체제마다 약간 다릅니다.

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

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

Windows에서 WXT은 chromiumProfile 및 keepProfileChanges 사용을 권장합니다. chromiumProfile 경로는 절대 경로여야 하므로 node:path의 resolve을 사용하십시오.

이점: 개발 세션 간에 프로필이 유지되므로 다음을 수행할 수 있습니다.

  • devtools 확장 설치
  • 로그인 기억
  • 브라우저 설정 유지

💡 팁: 영구 프로필은 Chromium 브라우저에만 적용됩니다. 예제에서 .wxt/chrome-data을 대체하여 각 프로젝트에 대해 별도의 프로필 디렉터리를 사용할 수 있습니다.

개발자 모드의 Google 로그인 문제

개발자 모드에서 Google 계정으로 로그인하려고 할 때 "이 브라우저 또는 앱은 안전하지 않을 수 있습니다." 오류가 발생하는 경우 자동화 감지를 비활성화해야 합니다.

해결책: web-ext.config.ts에 chromiumArgs을 추가하세요.

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

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

이렇게 하면 Google이 자동화된 브라우저의 로그인 시도를 차단하는 자동화 감지가 비활성화됩니다.

중단점 디버깅 문제

⚠️ 중단점 디버깅에 문제가 발생하는 경우 Chrome DevTools 무시 목록 설정 때문일 수 있습니다. 확장 프로그램에 의해 삽입된 콘텐츠 스크립트는 자동으로 무시되어 중단점이 실패할 수 있습니다.

해결책:

  1. 웹페이지에서 DevTools 열기
  2. 오른쪽 상단에 있는 설정 아이콘(⚙️)을 클릭하세요.
  3. 왼쪽 탐색 메뉴에서 "목록 무시"를 선택하세요.
  4. "확장에 의해 삽입된 콘텐츠 스크립트" 옵션이 선택 취소되어 있는지 확인하세요.

Chrome Ignore List

macOS: 열린 파일이 너무 많음 오류(EMFILE)

pnpm dev을 실행할 때 macOS에서 이 오류가 발생하는 경우:

Emfile Error

이는 Chokidar(Vite/WXT)에서 사용하는 파일 감시 라이브러리가 기본적으로 macOS의 기본 FSEvents를 사용하기 때문에 발생합니다. 이를 위해서는 각 감시 파일에 대한 파일 설명자가 필요합니다/directory. 대규모 프로젝트는 시스템 제한을 초과할 수 있습니다.

해결책: 파일 설명자가 필요하지 않은 폴링 모드로 전환하려면 CHOKIDAR_USEPOLLING=true을 설정하십시오.

프로젝트 루트에서 .env 파일을 생성하거나 업데이트합니다.

# .env
CHOKIDAR_USEPOLLING=true

그 후에는 pnpm dev이 EMFILE 오류 없이 작동합니다.

참고: 폴링 모드는 약간 느리고 더 많은 CPU를 사용하지만 파일 설명자 제한 문제를 방지합니다.

코드 제출

새 지점 만들기

# 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

병합 지점

원격 메인 브랜치가 업데이트되어 PR에서 충돌이 발생하는 경우 미리 원격 브랜치를 병합하여 해결할 수 있습니다. .

# 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.

이는 업스트림 리모컨이 1단계에서 구성되지 않았음을 의미합니다. 지금 추가하세요.

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

풀 요청 생성

Pull Request를 생성하기 전에 변경 사항을 문서화하기 위해 변경 세트를 추가해야 합니다.

버전 범프 이해

변경 사항에 따라 적절한 버전 범프 유형을 선택하세요.

  • 패치 - 버그 수정, 오타, 문서 업데이트, 사소한 개선
    • 예: 번역 오류 수정, README 업데이트, 버튼 스타일 수정, 성능 개선
  • 사소한 - 이전 버전과 호환되는 새로운 기능
    • 예: 번역 비활성화 버튼 추가, 어휘 내보내기 기능 추가
  • 주요 - 기존 기능에 영향을 미치는 주요 변경 사항
    • 예: API 구조 변경, 더 이상 사용되지 않는 기능 제거, 주요 리팩토링

변경 세트 추가

# 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

pnpm changeset을 실행하면 .changeset 디렉터리에 마크다운 파일이 생성됩니다. Pull Request를 생성하기 전에 이 파일을 편집하여 변경 사항에 대한 자세한 내용을 제공할 수 있습니다.

그런 다음 Pull Request를 생성하고 병합될 때까지 기다립니다.

커밋 컨벤션

커밋 메시지를 작성하기 위해 Conventional Commits 사양을 사용합니다.

환경 변수 설정

확장을 개발하는 동안 개발 환경을 위한 API 키와 같은 환경 변수를 자동으로 로드하려면 루트 디렉터리에 .env.development 파일을 생성하면 됩니다.

# .env.development
WXT_OPENAI_API_KEY=xxx
WXT_DEEPSEEK_API_KEY=xxx

WXT은 Vite 규칙에 따라 dotenv 파일을 로드합니다. import.meta.env을 통해 확장 코드에서 액세스해야 하는 변수에는 WXT_ 접두사를 사용해야 합니다.

단일 명령에 대한 환경 변수만 설정해야 하는 경우 구문은 셸에 따라 다릅니다.

SKIP_FREE_API=true pnpm test

기본 Windows 셸은 macOS/Linux KEY=value command 구문을 지원하지 않습니다. 이러한 이유로 명령이 실패하는 경우 위의 PowerShell 또는 CMD 양식을 사용하세요. 정기적으로 사용하는 WXT 변수의 경우 .env.development에 넣는 것이 좋습니다.

중국에서 Google API 테스트 건너뛰기

중국 본토의 기여자인 경우 코드를 푸시해야 할 때 다음 명령을 사용하십시오.

SKIP_FREE_API=true git push

이것이 왜 필요한가요? 푸시 프로세스 중에 코드 테스트가 수행되지만 중국 본토에서는 Google의 무료 API에 액세스할 수 없기 때문입니다. 이로 인해 테스트가 실패하고 푸시가 거부됩니다. SKIP_FREE_API 환경 변수를 설정하면 Google 테스트를 건너뜁니다.

어떤 종류의 PR이 검토되고 병합되나요?

기여 시작하기

이것이 첫 번째 PR 중 하나이고 진지하게 기여하려는 경우 일반적으로 품질 문제로 인해 거부되지 않습니다. 유지관리자는 문제를 식별하고 개발 프로세스 및 코드 스타일에 적응하도록 도와줄 것입니다. 그러나 다음 지침을 따르는 것이 좋습니다.

  1. 저장소의 "Good First Issue"와 같은 작은 문제부터 시작하세요. 작고 간단한 PR은 원활한 학습 과정을 제공합니다.
  2. PR이 모든 GitHub 작업 및 로컬 테스트를 통과했는지 확인하세요.

내 PR이 관리자의 검토를 받지 못하는 이유는 무엇입니까?

  1. 코드베이스에 익숙해지기 전에 지나치게 복잡한 PR을 작성하여 필요한 변경 사항이 너무 많이 발생했습니다.
  2. 귀하의 코드에는 많은 기본 오류가 포함되어 있어 관리자가 귀하의 심각성에 의문을 제기하게 됩니다.
    • 제거되지 않은 사용되지 않은 코드 조각
    • 과도하게 반복되는 코드
    • 변수 및 함수 이름이 너무 임의적입니다.
    • AI 지원 개발을 권장하지만 AI 생성 코드를 주의 깊게 검토하지 않아 품질이 낮거나 유지 관리가 불가능하거나 과도하게 엔지니어링된 코드가 발생했습니다.
  3. 유지관리자는 수정 제안을 여러 번 제공했지만 귀하는 이를 따르지 않았거나 변경 사항으로 근본적인 문제를 해결하지 못했습니다.

On this page

시작하기1단계: 리포지토리를 포크하고 로컬 머신에 복제2단계: 종속성 설치 및 개발 시작개발 팁pnpm Node.js 관리와 함께 npx 사용특정 브라우저에서 확장 프로그램 열기pnpm 개발자가 확장 프로그램을 자동으로 로드할 수 없습니다.영구 Chrome 프로필개발자 모드의 Google 로그인 문제중단점 디버깅 문제macOS: 열린 파일이 너무 많음 오류(EMFILE)코드 제출새 지점 만들기병합 지점풀 요청 생성버전 범프 이해변경 세트 추가커밋 컨벤션환경 변수 설정중국에서 Google API 테스트 건너뛰기어떤 종류의 PR이 검토되고 병합되나요?기여 시작하기내 PR이 관리자의 검토를 받지 못하는 이유는 무엇입니까?