貢献ガイド

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 で診断レポートジェネレーターを実行し、出力結果を添付することをお勧めします。同時に既知の問題を参照して既知の制限事項かどうかをご確認ください。

機能リクエスト

機能リクエストを提出する際は、以下を明記してください:

  • 使用シーンは何か?
  • この機能はどのような問題を解決するか?
  • 期待される動作は何か?
  • 代替案はあるか?
機能リクエスト提出前に、FlowPick の技術アーキテクチャ既知の制限事項を理解し、ニーズが技術的に実現可能であることを確認することをお勧めします。

ドキュメント改善

ドキュメント改善は最も参加しやすい貢献方法です:

  1. 改善が必要なドキュメントページを見つける
  2. ページ下部の「このページを編集」リンクをクリック(利用可能な場合)
  3. GitHub 上で直接編集して Pull Request を提出

または:

  1. リポジトリを Fork する
  2. content/ ディレクトリで該当する Markdown ファイルを見つける
  3. 修正後 Pull Request を提出

ドキュメント改善の一般的な方向性

方向説明参考
誤り修正技術的記述不正確、設定例誤りプロジェクトアーキテクチャで検証
詳細補足特定の機能に使用説明やパラメータ解説が欠けている機能ドキュメントのスタイルを参考
例示追加実際の使用シーンのコードや操作例が不足している使用シーンの書き方を参考
翻訳ドキュメントを他言語に翻訳多言語セクションを参照
リンク修正クロス参照リンクが無効または誤った場所を指している::note ブロック内のリンクを確認

コード貢献

コードを貢献したい場合、以下のフローに従ってください。


開発環境セットアップ

前提条件

ツール最小バージョン説明
Node.js18.xnvm または fnm でのバージョン管理推奨
pnpm8.xパッケージマネージャー
Git2.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 3UI フレームワーク
Nuxt UI v4コンポーネントライブラリ
Nuxt Content v3ドキュメントシステム
Tailwind CSS v4スタイリング
TypeScript型安全性
@ffmpeg/ffmpegブラウザサイドメディア処理
m3u8-parserHLS プレイリスト解析
mpd-parserDASH プレイリスト解析
streamsaverストリーミングファイル保存

開発規範

コードスタイル

プロジェクトでは ESLint を使用してコードチェックを行います:

pnpm lint

型チェック

pnpm typecheck

提出前に型チェックが通過していることを確認してください。

コミットメッセージ規範

Conventional Commits 形式を使用します:

<type>(<scope>): <description>

[optional body]

[optional footer]

タイプ(type):

タイプ説明
feat新機能
fixBug 修正
docsドキュメント更新
styleコードフォーマット(機能に影響なし)
refactorコードリファクタリング
perfパフォーマンス最適化
testテスト関連
choreビルド/ツール変更

例:

feat(downloader): 設定可能なスレッド数による並列セグメントダウンロード追加

並列セグメントダウンロードのためのワーカープールパターンを実装しました。
並列度レベルは 1-8 スレッド間で設定可能です。

Closes #42

ブランチ戦略

  • main:安定版、いつでもデプロイ可能
  • develop:開発ブランチ
  • feat/xxx:機能ブランチ
  • fix/xxx:修正ブランチ
  • docs/xxx:ドキュメントブランチ

Pull Request フロー

  1. リポジトリを Fork し機能ブランチを作成
  2. 開発を行い、コードが lint と typecheck を通過することを確認
  3. PR を develop ブランチに提出
  4. PR 記述で変更内容と理由を説明
  5. コードレビューを待つ

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)です。他言語を追加する場合:

  1. content/ 下に対応する言語ディレクトリを作成(例:en/
  2. ドキュメント構造をコピーし内容を翻訳
  3. ファイルパスと命名を一致させる

テスト

手動テストチェックリスト

ダウンロード機能に関連する PR 提出前、以下のシーンを検証してください:

  • 小容量ファイルダウンロード(<10MB)
  • 大容量ファイルダウンロード(>500MB)
  • 暗号化 HLS ストリームダウンロード
  • DASH ストリームダウンロード
  • フォーマット変換(TS → MP4)
  • 並列スレッド数切り替え
  • ダウンロードキャンセルとリトライ
  • Chrome ブラウザ
  • Edge ブラウザ

各テストシーンの検証ポイント

テストシーン検証ポイント参考ドキュメント
小容量ファイルダウンロードダウンロード完全性、速度表示、プログレスバーダウンロードエンジンアーキテクチャ
大容量ファイルダウンロードメモリ占有率、ストリーミング書き込み、クラッシュなしダウンロードエンジンアーキテクチャ — メモリセキュリティ管理
暗号化 HLSAES-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 を使用する方法についてはオンラインツールをご参照ください。

リリースフロー

  1. develop ブランチで開発とテストを完了
  2. content/zh-Hans/4.changelog/ の更新ログを更新
  3. developmain にマージ
  4. バージョンタグを作成(例:v1.1.0
  5. 拡張機能パッケージをビルドし Chrome Web Store に提出

関連ドキュメント