기여 가이드라인
FlowPick 프로젝트에 코드, 문서 또는 버그 리포트를 기여하는 방법.
FlowPick 프로젝트에 관심을 가져주셔서 감사합니다. 이 문서에서는 코드 제출, 문서 개선, 문제 보고 등 프로젝트에 참여하는 방법을 안내합니다.
행동 강령
본 프로젝트에 참여함으로써 다음 기본 원칙을 준수하는 데 동의하게 됩니다:
- 친화적이고 포용적인 언어 사용
- 다양한 관점과 경험 존중
- 건설적인 비판 수용
- 커뮤니티에 가장 유익한 것에 집중
- 다른 커뮤니티 구성원에게 공감 표현
기여 방법
버그 보고
버그를 발견하면 GitHub Issues를 통해 보고해 주세요. 좋은 버그 리포트에는 다음이 포함되어야 합니다:
제목: 문제를 간결하게 설명
설명:
- 예상되는 동작은 무엇입니까?
- 실제로 어떤 일이 발생했습니까?
재현 단계:
1. '...' 열기
2. '...' 클릭
3. '...'까지 스크롤
4. 오류 관찰
환경 정보:
- 운영 체제: Windows 11 / macOS 14 / Ubuntu 24.04
- 브라우저: Chrome 125 / Edge 125
- FlowPick 버전: v1.0.0
- 확장 프로그램 버전 또는 온라인 도구?
추가 정보:
- 콘솔 오류 로그
- 스크린샷 또는 화면 녹화
- 관련 스트리밍 URL(공개적으로 접근 가능한 경우)
버그를 제출하기 전에 Console에서 진단 리포트 생성기를 실행하여 출력 결과를 함께 첨부하는 것이 좋습니다. 또한 알려진 문제를 확인하여 이미 기록된 알려진 제한 사항인지 확인하세요.
기능 요청
기능 요청을 제출할 때 다음을 명시하세요:
- 사용 시나리오는 무엇입니까?
- 이 기능은 어떤 문제를 해결합니까?
- 기대하는 동작은 무엇입니까?
- 대안이 있습니까?
문서 개선
문서 개선은 참여하기 가장 쉬운 기여 방법입니다:
- 개선이 필요한 문서 페이지 찾기
- 페이지 하단의 "이 페이지 편집" 링크 클릭(사용 가능한 경우)
- GitHub에서 직접 편집하고 Pull Request 제출
또는:
- 저장소 Fork
content/디렉토리에서 해당 Markdown 파일 찾기- 수정 후 Pull Request 제출
문서 개선의 일반적인 방향:
| 방향 | 설명 | 참조 |
|---|---|---|
| 오류 수정 | 기술 설명이 부정확하거나 구성 예시가 잘못됨 | 프로젝트 아키텍처로 검증 |
| 세부 정보 보충 | 특정 기능에 사용 설명이나 매개변수 설명이 누락됨 | 기능 문서 스타일 참조 |
| 예시 추가 | 실제 사용 시나리오에 대한 코드 또는 작업 예시가 부족함 | 사용 사례 작법 참조 |
| 번역 | 문서를 다른 언어로 번역 | 다국어 장 참조 |
| 링크 수정 | 상호 참조 링크가失效되거나 잘못된 위치를 가리킴 | ::note 블록 내 링크 확인 |
코드 기여
코드를 기여하고 싶다면 다음 절차를 따르세요.
개발 환경 설정
필수 조건
| 도구 | 최소 버전 | 설명 |
|---|---|---|
| Node.js | 18.x | nvm 또는 fnm으로 버전 관리 권장 |
| pnpm | 8.x | 패키지 매니저 |
| Git | 2.x | 버전 관리 |
클론 및 설치
git clone https://github.com/ezwebtools/flowpick.git
cd flowpick-web
pnpm install
개발 서버 시작
pnpm dev
개발 서버는 기본적으로 http://localhost:3000에서 실행됩니다.
FFmpeg WASM 멀티스레드 모드를 테스트해야 하는 경우, 개발 서버가 올바른 COEP/COOP 응답 헤더로 구성되어 있는지 확인하세요. 자세한 내용은 브라우저 호환성 — 고급 API를 참조하세요.
프로젝트 구조
flowpick-web/
├── app/ # 애플리케이션 소스 코드
│ ├── assets/ # 정적 리소스(CSS)
│ ├── components/ # Vue 컴포넌트
│ │ └── content/ # Nuxt Content 전용 컴포넌트
│ ├── composables/ # Composable 함수
│ │ ├── useFFmpeg.ts # FFmpeg WASM 통합
│ │ ├── useStreamMerge.ts # 스트림 병합 및 다운로드 엔진
│ │ ├── useClarity.ts # Microsoft Clarity 분석
│ │ └── useGA4.ts # Google Analytics
│ ├── layouts/ # 레이아웃 컴포넌트
│ ├── pages/ # 페이지 라우팅
│ │ ├── docs/ # 문서 페이지
│ │ ├── changelog/ # 변경 로그 페이지
│ │ ├── legal/ # 법률 페이지
│ │ ├── m3u8-downloader.vue # M3U8 다운로더
│ │ ├── dash-downloader.vue # DASH 다운로더
│ │ └── index.vue # 홈페이지
│ ├── types/ # TypeScript 타입 선언
│ ├── app.config.ts # 애플리케이션 설정
│ └── app.vue # 루트 컴포넌트
├── content/ # Nuxt Content 문서
│ └── zh-Hans/ # 간体中文 문서
├── public/ # 공용 정적 리소스
│ ├── ffmpeg/ # FFmpeg WASM 핵심 파일
│ └── ffmpeg-mt/ # FFmpeg WASM 멀티스레드 핵심 파일
├── nuxt.config.ts # Nuxt 설정
├── package.json # 프로젝트 의존성
└── tsconfig.json # TypeScript 설정
각 모듈의 상세 역할, 데이터 흐름 및 설계 결정에 대해서는 프로젝트 아키텍처를 참조하세요. 다운로드 엔진의 완전한 기술 구현에 대해서는 다운로드 엔진 아키텍처를 참조하세요.
기술 스택
| 기술 | 용도 |
|---|---|
| Nuxt 4 | 풀스택 프레임워크 |
| Vue 3 | UI 프레임워크 |
| Nuxt UI v4 | 컴포넌트 라이브러리 |
| Nuxt Content v3 | 문서 시스템 |
| Tailwind CSS v4 | 스타일링 |
| TypeScript | 타입 안전성 |
| @ffmpeg/ffmpeg | 브라우저 측 미디어 처리 |
| m3u8-parser | HLS 매니페스트 파싱 |
| mpd-parser | DASH 매니페스트 파싱 |
| streamsaver | 스트리밍 파일 저장 |
개발 규칙
코드 스타일
프로젝트는 ESLint를 사용하여 코드를 검사합니다:
pnpm lint
타입 검사
pnpm typecheck