貢献ガイド
FlowPick プロジェクトにコード、ドキュメント、問題フィードバックを貢献する方法。
FlowPick プロジェクトへの関心に感謝いたします。本ドキュメントはプロジェクトへの参加方法をガイドし、コード提出、ドキュメント改善、問題フィードバックを含みます。
行動規範
本プロジェクトへの参加は、以下の基本原則の遵守に同意することを意味します:
- 友好的で包摂的な言語を使用する
- 異なる視点と経験を尊重する
- 建設的に批評を受け入れる
- コミュニティにとって最も有益なことに注目する
- 他のコミュニティメンバーに共感を示す
貢献方法
Bug 報告
Bug を発見した場合は、GitHub Issues 経由で報告を提出してください。良い Bug レポートには以下が含まれるべきです:
タイトル:簡潔な問題説明
説明:
- 期待される動作は何か?
- 実際には何が起きたか?
再現手順:
1. '...' を開く
2. '...' をクリック
3. '...' までスクロール
4. エラーを観察
環境情報:
- OS:Windows 11 / macOS 14 / Ubuntu 24.04
- ブラウザ:Chrome 125 / Edge 125
- FlowPick バージョン:v1.0.0
- 拡張機能版かオンラインツールか?
追加情報:
- コンソールエラーログ
- スクリーンショットまたは録画画面
- 関連するストリーミング URL(公開アクセス可能な場合)
Bug 提出前に、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/ # コンポーザブル関数
│ │ ├── 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
提出前に型チェックが通過していることを確認してください。
コミットメッセージ規範
Conventional Commits 形式を使用します:
<type>(<scope>): <description>
[optional body]
[optional footer]
タイプ(type):
| タイプ | 説明 |
|---|---|
feat | 新機能 |
fix | Bug 修正 |
docs | ドキュメント更新 |
style | コードフォーマット(機能に影響なし) |
refactor | コードリファクタリング |
perf | パフォーマンス最適化 |
test | テスト関連 |
chore | ビルド/ツール変更 |
例:
feat(downloader): 設定可能なスレッド数による並列セグメントダウンロード追加
並列セグメントダウンロードのためのワーカープールパターンを実装しました。
並列度レベルは 1-8 スレッド間で設定可能です。
Closes #42
ブランチ戦略
main:安定版、いつでもデプロイ可能develop:開発ブランチfeat/xxx:機能ブランチfix/xxx:修正ブランチdocs/xxx:ドキュメントブランチ
Pull Request フロー
- リポジトリを Fork し機能ブランチを作成
- 開発を行い、コードが lint と typecheck を通過することを確認
- PR を
developブランチに提出 - PR 記述で変更内容と理由を説明
- コードレビューを待つ
PR レビューの注目点:
| 注目点 | 説明 |
|---|---|
| 機能正確性 | 変更が期待された機能を実現しているか、境界ケースが処理されているか |
| コード品質 | 既存のコードスタイルに従っているか、重複コードがないか |
| パフォーマンス影響 | 不必要なオーバーヘッドを導入していないか、大容量ファイルシーンを考慮しているか |
| 互換性 | 既存機能に影響を与えていないか、ブラウザ互換性を考慮しているか |
| セキュリティ | セキュリティリスクを導入していないか、ユーザーデータが保護されているか |
ダウンロードエンジンのパフォーマンス考慮(並列制御、メモリ管理、リトライ戦略)についてはダウンロードエンジンアーキテクチャをご参照ください。ブラウザ互換性の注意点についてはブラウザ互換性をご参照ください。
ドキュメント作成ガイド
ドキュメント構造
ドキュメントは Nuxt Content v3 を使用し、Markdown ファイル形式で content/zh-Hans/ ディレクトリ下に配置されます。
Frontmatter
各ドキュメントファイルには以下の frontmatter が必要です:
---
title: ドキュメントタイトル
description: ドキュメント説明(SEO および一覧表示用)
navigation:
icon: i-lucide-xxx # Lucide アイコン名
---
コンテンツフォーマット
- Markdown 標準構文を使用
- コードブロックで言語指定してシンタックスハイライト有効化
- 表格は比較・参照情報に使用
::tip、::note、::warningなどの Nuxt Content ディレクティブを使用
ナビゲーション設定
各ドキュメントディレクトリには .navigation.yml ファイルが必要です:
title: 分類名
icon: i-lucide-xxx
多言語
現在ドキュメントは主に簡体字中国語(zh-Hans)です。他言語を追加する場合:
content/下に対応する言語ディレクトリを作成(例:en/)- ドキュメント構造をコピーし内容を翻訳
- ファイルパスと命名を一致させる
テスト
手動テストチェックリスト
ダウンロード機能に関連する PR 提出前、以下のシーンを検証してください:
- 小容量ファイルダウンロード(<10MB)
- 大容量ファイルダウンロード(>500MB)
- 暗号化 HLS ストリームダウンロード
- DASH ストリームダウンロード
- フォーマット変換(TS → MP4)
- 並列スレッド数切り替え
- ダウンロードキャンセルとリトライ
- Chrome ブラウザ
- Edge ブラウザ
各テストシーンの検証ポイント:
| テストシーン | 検証ポイント | 参考ドキュメント |
|---|---|---|
| 小容量ファイルダウンロード | ダウンロード完全性、速度表示、プログレスバー | ダウンロードエンジンアーキテクチャ |
| 大容量ファイルダウンロード | メモリ占有率、ストリーミング書き込み、クラッシュなし | ダウンロードエンジンアーキテクチャ — メモリセキュリティ管理 |
| 暗号化 HLS | AES-128 復号、キー取得 | 動画メディア検知 — 暗号化ストリーム |
| DASH ストリーム | 音视频分離、FMP4 再構成 | ダウンロードエンジンアーキテクチャ — DASH ストリームの特殊処理 |
| フォーマット変換 | FFmpeg ロード、リマックス正確性 | フォーマット変換 — FFmpeg WASM エンジン |
| 並列切り替え | スレッド数変化、速度比較 | 設定参考 |
| キャンセルとリトライ | AbortController、リトライ回数 | ダウンロードエンジンアーキテクチャ — リトライ機構 |
| ブラウザ互換性 | Chrome/Edge 機能一貫性 | ブラウザ互換性 |
テスト用ストリーミング URL
テストに使用できる公開ストリームの一部:
# 基礎 HLS(暗号化なし)
https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8
# マルチ画質 HLS
https://test-streams.mux.dev/pts_shift/pts_shift.m3u8
# 基礎 DASH
https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd
HLS および DASH ストリームの検出原理とプレイリスト構造については動画メディア検知をご参照ください。オンラインツールでこれらのテスト URL を使用する方法についてはオンラインツールをご参照ください。
リリースフロー
developブランチで開発とテストを完了content/zh-Hans/4.changelog/の更新ログを更新developをmainにマージ- バージョンタグを作成(例:
v1.1.0) - 拡張機能パッケージをビルドし Chrome Web Store に提出
関連ドキュメント
- プロジェクトアーキテクチャ — システム設計、モジュール責任範囲とデータフロー
- ダウンロードエンジンアーキテクチャ — コアダウンロードエンジンの完全な技術実装
- 動画メディア検知 — HLS/DASH プレイリスト解析と暗号化検出
- フォーマット変換 — FFmpeg WASM エンジンと出力フォーマット
- ブラウザ互換性 — 各ブラウザ API サポートとダウングレード戦略
- オンラインツール — オンラインツールの使用と制限
- 設定参考 — 並列数、フィルタなどの設定項目
- 既知の問題 — 現在のバージョンの技術的制限と境界ケース
- 一般的な問題のトラブルシューティング — 診断ツールとトラブルシューティング手順
- 使用シーン — 各シーンの使用ドキュメント参考