Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
180 lines (122 loc) · 6.33 KB

CONTRIBUTING.md

File metadata and controls

180 lines (122 loc) · 6.33 KB
Raw

Contributing to ModuWeb

ModuWeb에 기여해 주셔서 감사합니다! 이 문서는 기여 방법을 안내합니다.

목차

행동 강령

모든 기여자는 서로를 존중하고 건설적인 방식으로 소통해 주세요.

개발 환경 설정

1. 저장소 Fork 및 Clone

git clone https://github.com/YOUR_USERNAME/ModuWeb.git
cd ModuWeb

2. 설정 파일 생성

설정 원천은 .env 파일 하나입니다. .env.example을 복사해 값을 채우면, 빌드 시 config.json이 자동 생성됩니다.

# Windows
copy .env.example .env

# macOS / Linux
cp .env.example .env

값을 채운 뒤 npm run config:from-env(수동) 또는 그냥 npm run build(자동)를 실행하세요. 변수별 설명·config 경로 대응표는 .env.example 주석과 README의 ".env 변수 ↔ config 경로 대응표"에 있습니다.

.env 없이 config.example.json을 config.json으로 복사해 직접 관리해도 됩니다 — .env에 WAT_* 변수가 없으면 빌드가 수동 config.json을 덮어쓰지 않습니다.

로컬에서 사전 기능을 테스트하려면 WAT_DICTIONARY_ENDPOINT가 사전 중계(프록시) 주소여야 합니다. examples/dict_sample.json은 응답 형식 예시이므로 그대로 serverEndpoint로 연결할 수 없을 수 있습니다.

3. 의존성 설치

npm install

4. 소스 편집 및 빌드

소스 코드는 dist/가 아니라 src/ 폴더에서 편집합니다. dist/의 파일은 Rollup 빌드 산출물이므로 직접 수정하지 마세요 (다음 빌드 시 덮어써집니다).

src/는 19개 모듈로 구성됩니다 (wat/ 2, core/ 9, tts/ 5, stt/ 2, index.js). 자세한 구조는 ARCHITECTURE.md의 "소스 모듈 레이아웃"을 참고하세요.

# 프로덕션 번들 생성 (dist/webAccTools.js 등)
npm run build

# 파일 변경을 감지해 자동 재빌드
npm run build:watch

5. 테스트 실행

npm test

Jest 기반 단위 테스트가 tests/unit/에 있습니다. 브라우저 수동 테스트 체크리스트는 tests/manual/checklist.md를 참고하세요.

6. 브라우저에서 확인

빌드 후 examples/ 폴더의 HTML 파일을 브라우저에서 열어 실제 동작을 확인합니다.

기여 방법

  1. 작업할 이슈를 Issues에서 찾거나 새로 등록하세요.
  2. 이슈 번호에 맞는 브랜치를 생성합니다.
    예: feature/123-add-new-font, fix/456-tts-crash
  3. src/에서 변경 사항을 구현하고 npm run build 후 npm test 및 examples/ 폴더에서 직접 테스트합니다.
  4. 변경 이유를 명확히 담은 커밋 메시지를 작성합니다.
  5. Pull Request를 main 브랜치 대상으로 생성합니다.

코딩 스타일

  • 언어: Vanilla JavaScript (ES2022+, class 문법, async/await)
  • 들여쓰기: 탭(Tab) 사용
  • 세미콜론: 사용
  • 변수 선언: const 우선, 재할당 필요 시 let. var 사용 금지
  • JSDoc: 모든 public 메서드에 JSDoc 주석 작성 (한국어/영어 병기)
  • 에러 처리: WAT.ErrorHandler 클래스를 통한 중앙집중식 처리
  • DOM 조작: innerHTML 직접 할당 지양, createElement + setAttribute 사용

금지 사항

  • var 키워드 사용
  • for...in 루프 내 hasOwnProperty 직접 호출 (대신 Object.keys() 또는 Object.hasOwn() 사용)
  • 외부 API 키나 서버 URL을 코드에 직접 하드코딩 (반드시 .env → config.json 경유). 비밀키 자체는 어디에도 금지 — config.json은 브라우저에 배포되는 공개 파일이며, 생성 스크립트가 API_KEY/SECRET/TOKEN 류 변수명을 거부합니다. 키는 서버 프록시 안에서만 사용하세요.
  • jQuery 등 외부 라이브러리 의존성 추가

커밋 메시지 규칙

Conventional Commits 형식을 따릅니다.

<type>(<scope>): <subject>

[optional body]

type 종류:

type 설명
feat 새로운 기능 추가
fix 버그 수정
refactor 기능 변경 없는 코드 개선
docs 문서 수정
style 코드 스타일(포맷) 수정
chore 빌드 설정, 의존성 등 기타 변경

예시:

feat(tts): 읽기 속도 단계별 조절 기능 추가
fix(dictionary): JSONP 타임아웃 후 콜백 누수 수정
refactor(config): 하드코딩된 폰트 URL을 config.json으로 이동
docs(readme): 로컬 개발 환경 설정 가이드 추가

Pull Request 절차

  1. PR 제목은 커밋 메시지 규칙을 따릅니다.
  2. PR 설명에 다음 항목을 포함합니다:
    • 변경 이유 및 방법
    • 테스트한 브라우저 목록
    • 관련 이슈 번호 (Closes #123)
  3. config.json은 PR에 포함하지 마세요 (.gitignore 대상).
  4. 변경 사항이 기존 기능을 깨지 않는지 npm test 및 examples/ 폴더에서 직접 확인하세요.
  5. dist/ 재빌드 산출물의 커밋 포함 여부는 프로젝트 관리자 정책을 따르세요 (소스는 항상 src/에서 수정).

버그 리포트

Issues에 다음 내용을 포함하여 등록해 주세요.

  • 재현 방법: 단계별로 상세히 기술
  • 기대 동작: 어떻게 동작해야 하는지
  • 실제 동작: 현재 어떻게 동작하는지
  • 환경: 브라우저 종류/버전, OS
  • 재현 가능한 예제: 가능하다면 코드 스니펫 또는 링크

기능 요청

Issues에 enhancement 라벨과 함께 등록해 주세요.

  • 기능의 목적과 사용 사례를 설명해 주세요.
  • 가능하다면 예상 API 또는 사용법을 포함해 주세요.

감사합니다! 여러분의 기여가 ModuWeb을 더 나은 접근성 도구로 만듭니다.