Contributing Guide

Thank you for your interest in the FlowPick project. This document guides you on how to participate in project contributions, including code submissions, documentation improvements, and issue reporting.

Code of Conduct

By participating in this project, you agree to follow these basic principles:

• Use friendly and inclusive language
• Respect different viewpoints and experiences
• Accept constructive criticism gracefully
• Focus on what's best for the community
• Show empathy toward other community members

Ways to Contribute

Reporting Bugs

If you find a bug, please submit a report via GitHub Issues. A good bug report should include:

Title: Brief description of problem

Description:
- What is expected behavior?
- What actually happened?

Steps to Reproduce:
1. Open '...'
2. Click on '...'
3. Scroll to '...'
4. See error

Environment Information:
- OS: Windows 11 / macOS 14 / Ubuntu 24.04
- Browser: Chrome 125 / Edge 125
- FlowPick version: v1.0.0
- Extension version or online tools?

Additional Info:
- Console error logs
- Screenshots or recordings
- Relevant streaming URL (if publicly accessible)

Feature Requests

When submitting feature requests, please explain:

• What is your use case?
• What problem does this feature solve?
• What is your expected behavior?
• Are there alternative solutions?

Improving Documentation

Documentation improvement is the easiest way to contribute:

1. Find a documentation page that needs improvement
2. Click "Edit this page" link at bottom of page (if available)
3. Edit directly on GitHub and submit Pull Request

Or:

1. Fork repository
2. Find corresponding Markdown file under content/ directory
3. Make changes and submit Pull Request

Common directions for documentation improvements:

Contributing Code

If you want to contribute code, please follow this workflow.

Development Environment Setup

Prerequisites

Clone & Install

git clone https://github.com/ezwebtools/flowpick.git
cd flowpick-web
pnpm install

Start Development Server

pnpm dev

Development server runs at http://localhost:3000 by default.

Project Structure

flowpick-web/
├── app/                    # Application source code
│   ├── assets/             # Static assets (CSS)
│   ├── components/         # Vue components
│   │   └── content/        # Nuxt Content specific components
│   ├── composables/        # Composables
│   │   ├── useFFmpeg.ts    # FFmpeg WASM integration
│   │   ├── useStreamMerge.ts # Stream merge & download engine
│   │   ├── useClarity.ts   # Microsoft Clarity analytics
│   │   └── useGA4.ts       # Google Analytics
│   ├── layouts/            # Layout components
│   ├── pages/              # Page routes
│   │   ├── docs/           # Documentation pages
│   │   ├── changelog/      # Changelog pages
│   │   ├── legal/          # Legal pages
│   │   ├── m3u8-downloader.vue  # M3U8 downloader
│   │   ├── dash-downloader.vue  # DASH downloader
│   │   └── index.vue       # Homepage
│   ├── types/              # TypeScript type declarations
│   ├── app.config.ts       # Application configuration
│   └── app.vue             # Root component
├── content/                # Nuxt Content documentation
│   └── zh-Hans/            # Simplified Chinese docs
├── public/                 # Public static assets
│   ├── ffmpeg/             # FFmpeg WASM core files
│   └── ffmpeg-mt/          # FFmpeg WASM multithread core files
├── nuxt.config.ts          # Nuxt configuration
├── package.json            # Project dependencies
└── tsconfig.json           # TypeScript configuration

Tech Stack

Development Standards

Code Style

Project uses ESLint for code linting:

pnpm lint

Type Checking

pnpm typecheck

Ensure type checking passes before submitting.

Commit Message Convention

Use Conventional Commits format:

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

[optional body]

[optional footer]

Types (type):

Example:

feat(downloader): add concurrent segment download with configurable threads

Implemented worker pool pattern for parallel segment downloading.
Concurrency level can be configured between 1-8 threads.

Closes #42

Branch Strategy

• main: Stable version, always deployable
• develop: Development branch
• feat/xxx: Feature branch
• fix/xxx: Bug fix branch
• docs/xxx: Documentation branch

Pull Request Workflow

1. Fork repository and create feature branch
2. Develop, ensure code passes lint and typecheck
3. Submit PR to develop branch
4. Describe changes and reasons in PR description
5. Wait for code review

PR Review Focus Areas:

Documentation Writing Guide

Document Structure

Documentation uses Nuxt Content v3, stored as Markdown files in content/zh-Hans/ directory.

Frontmatter

Each document file must include following frontmatter:

---
title: Document Title
description: Document description (for SEO and list display)
navigation:
  icon: i-lucide-xxx  # Lucide icon name
---

Content Format

• Use standard Markdown syntax
• Specify language in code blocks for syntax highlighting
• Tables for comparison and reference information
• Use Nuxt Content directives like ::tip, ::note, ::warning, etc.

Navigation Configuration

Each document directory needs a .navigation.yml file:

title: Category Name
icon: i-lucide-xxx

Multilingual

Currently documentation primarily in Simplified Chinese (zh-Hans). To add other languages:

1. Create corresponding language directory under content/ (e.g., en/)
2. Copy document structure and translate content
3. Keep file paths and naming consistent

Testing

Manual Testing Checklist

Before submitting PRs involving download functionality, verify these scenarios:

• Small file download (<10MB)
• Large file download (>500MB)
• Encrypted HLS stream download
• DASH stream download
• Format conversion (TS → MP4)
• Concurrent thread count switching
• Download cancellation and retry
• Chrome browser
• Edge browser

Verification Points for Each Test Scenario:

Test Streaming URLs

Here are some publicly available streams for testing:

# Basic HLS (no encryption)
https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8

# Multi-quality HLS
https://test-streams.mux.dev/pts_shift/pts_shift.m3u8

# Basic DASH
https://dash.akamaized.net/akamai/bbb_30fps/bbb_30fps.mpd

Release Process

1. Complete development and testing on develop branch
2. Update changelog in content/zh-Hans/4.changelog/
3. Merge develop into main
4. Create version tag (e.g., v1.1.0)
5. Build extension package and submit to Chrome Web Store

Related Documentation

• Project Architecture — System design, module responsibilities, and data flow
• Download Engine Architecture — Complete technical implementation of core download engine
• Video Sniffing — HLS/DASH manifest parsing and encryption detection
• Format Conversion — FFmpeg WASM engine and output formats
• Browser Compatibility — Browser API support and degradation strategies
• Online Tools — Online tool usage and limitations
• Configuration Reference — Concurrency, filter, and other settings
• Known Limitations — Current version technical limitations and edge cases
• Common Issues Troubleshooting — Diagnostic tools and troubleshooting steps
• Use Cases — Usage documentation references by scenario