Contributing Guide
Contributions of code, bug reports, and feature proposals are welcome.
Contributions whose main purpose is to promote a commercial service (for example, adding an integration for one particular service, or adding service recommendations and links to the docs) do not go through the PR process, and such PRs will be closed. For collaboration, contact support@arc-reel.com.
ArcReel assumes that contributors develop with a coding Agent. AGENTS.md at the repository root (CLAUDE.md is a link to it) is the Agent's entry point; gate commands, test selection, and coding standards are all linked from there. This page covers only what contributors themselves need to know.
Local Development Environment
# Prerequisites: Python 3.12+, Node.js 24.12.0+, uv, pnpm (ffmpeg ships with the Python dependency imageio-ffmpeg)
# The documentation site website/ pins its Node version in website/.node-version
# Operating system: Linux / macOS / Windows WSL2; native Windows can run project creation and basic workflows,
# but the Agent sandbox on Windows degrades to a command-prefix allowlist (see docs/adr/0025); WSL2/Docker is recommended for production
# Install dependencies
uv sync
cd frontend && pnpm install && cd ..
# Install the pre-commit hooks once (ruff / eslint / actionlint / zizmor)
uv run pre-commit install
# Initialize the database
uv run alembic upgrade head
# Start the backend (terminal 1)
# Note: --reload-dir is required to limit the watched directories; otherwise watchfiles scans
# node_modules / .venv / .git / .worktrees and hundreds of thousands of files, using over 50% of one CPU core
uv run uvicorn server.app:app --reload --reload-dir server --reload-dir lib --port 1241
# Start the frontend (terminal 2)
cd frontend && pnpm dev
# Open http://localhost:5173
Documentation Site
website/ is a separate package root with its own lockfile and is not grouped into a workspace with frontend:
cd website && pnpm install
pnpm start # Development preview
pnpm build # Dual-locale build; a broken link or anchor fails the build
pnpm typecheck
pnpm lint # ESLint
pnpm format # Writes prettier formatting; format:check only verifies without modifying
pnpm check # sync-contributing + typecheck + lint + format:check + check-consistency; excludes build and scripts/*.test.mjs
# Site search only works against build output, not in the dev server
pnpm build && pnpm serve
# Sync the repo-root CONTRIBUTING.md into the development-section page (start / build already run this automatically, so a manual run is rarely needed)
pnpm sync-contributing
# CI consistency check: page inventory / orphan translations / published headings missing an explicit anchor / UI JSON key completeness — exits non-zero if any check fails;
# it depends on the output of sync-contributing, so run sync-contributing first
pnpm check-consistency
Testing
For the development loop and the full gate before pushing, see "工具链与校验" (Toolchain and checks) in AGENTS.md and docs/agents/testing.md. CI runs the same set of checks.
Code Quality
The entry point for coding standards is CODING_STANDARDS.md: it maps changed paths to the domain standards under docs/standards/, and it contains only project conventions that require judgment and cannot be replaced by tooling. Both local reviews and the AI reviewer on PRs use it as their basis.
Dependency Management
For the steps to add or upgrade a dependency, see docs/agents/dependencies.md.
Documentation Maintenance
The only published location for user documentation is docs.arc-reel.com; source files live in website/docs/ (see "Documentation Site" above for local builds and previews). Chinese is the sole authoring source; English translations are generated by AI, and humans review only the Chinese source. Internal documentation (ADRs, GLOSSARY.md, AGENTS.md, the security threat model, provider API documentation indexes, and so on) is not published on the site and remains under the repository's docs/ directory. SECURITY.md also remains in the repository root because the GitHub Security tab depends on it.
This file is the source of truth for the contributing guide. During builds, it is copied to the site's development section (website/scripts/sync-contributing.mjs); the Chinese copy is not committed.
Page Responsibilities
Published pages also declare their documentation-refresh coverage tier via the update_docs frontmatter key; the criteria live in .agents/skills/update-docs/SKILL.md.
| Page | Should contain | Should not contain |
|---|---|---|
README.md | Product positioning, core value, and the shortest path to getting started | A complete model list, every environment variable, or internal implementation details |
website/docs/index.mdx | Documentation-site positioning, primary entry points, and a navigation overview | Complete instructions for specific features |
website/docs/guide/getting-started.md | The complete path from deployment to the first final video | Production-grade reverse proxy and backup strategies |
website/docs/guide/workflows.md | Content modes, generation modes, content review checkpoints, and selection guidance | Provider credentials and operations commands |
website/docs/guide/providers.md | Provider types, capability coverage, selection principles, and configuration hierarchy | Price promises likely to become outdated |
website/docs/guide/comfyui.md | Importing ComfyUI workflows, node binding, conversion semantics for size/duration/seed, testing, and runtime limits | Deploying ComfyUI itself or installing custom nodes |
website/docs/guide/market.md | Managing market sources, confirming installation of market entries, updating, and uninstalling | Contribution workflow and steps for hosting a market source (the official market source repository docs are authoritative) |
website/docs/guide/jianying-export.md | Locating the Jianying draft directory, exporting, and further editing steps | The video generation process itself |
website/docs/guide/faq.md | Frequently asked questions and short answers | Long tutorials |
website/docs/ops/deployment.md | Deployment, upgrades, backup, recovery, monitoring, and security | Product marketing copy |
website/docs/ops/migrate-to-postgres.md | SQLite-to-PostgreSQL migration, verification, and rollback steps | Day-to-day PostgreSQL deployment and operations guidance |
website/docs/dev/architecture.md | Stable architectural boundaries, data flows, and extension points | Temporary implementation plans and incomplete designs |
SECURITY.md | Supported versions, supported deployment boundaries, private vulnerability reporting, and coordinated disclosure policy | Details of unfixed vulnerabilities and dynamic risk registers |
docs/security/threat-model.md | Security assets, trust boundaries, attack surfaces, existing controls, and reassessment triggers | Directly exploitable unfixed vulnerabilities and patch history |
Writing Conventions
For writing standards for published pages and the README, see docs/standards/docs.md. For which documents a feature change must update, see "功能变更与对应文档在同一个 PR 里" (Feature changes and their documentation land in the same PR) in docs/standards/general.md. Write every heading on a published page as ## 标题 {#english-id}; the Chinese and English locales share the same anchor.
Workflow
Branch Strategy (trunk-based)
mainis the only long-lived branch. Complete all work on short-lived branches created from the latestmain, then merge them back intomainthrough a PR- Never push directly to
main. Personal branches are merged through the PR process as well; review the diff and acceptance checklist yourself before submitting
Branch Naming Convention
Use <type>/<slug>, where type is one of the conventional commit types:
Short-lived run branches of the AFK team workflow are the exception: they use afk/<batch-id>/stage-<K> and issue/<N>.
feat/— New feature (for example,feat/reference-video-backend)fix/— Bug fix (for example,fix/queue-lease-timeout)refactor/— Refactoring (for example,refactor/session-actor)docs/— Documentation only (for example,docs/contribution-infra)chore/— Builds / tooling / version numbers / cleanup (for example,chore/freeze-versions)ci/— CI configuration (for example,ci/testing-discipline)test/— Tests only
Use lowercase words separated by hyphens for slug, briefly describing the branch's topic.
Short Branch Lifetime
The time from creation to merge must be ≤ 3 days. If a branch runs longer, split it or rebase it onto the main line first; avoid submitting a long-lived branch directly for review.
Squash Merge
Squash each PR into one commit when merging back into main, with a commit message that follows the conventional commits specification (see the next section). Choose "Squash and merge" on GitHub.
Stage PRs created by afk-team-workflow are the exception: they use "Rebase and merge" to preserve each issue's conventional commit; non-issue commits produced by cleanup and the review loop are squashed into one conventional integration-fix commit before merging.
Commit Conventions
Commit messages follow the Conventional Commits format:
feat: 新增功能描述
fix: 修复问题描述
refactor: 重构描述
docs: 文档变更
chore: 构建/工具变更
The title format is type(scope): 摘要; scope is optional. With squash merging, the PR title becomes the changelog entry: describe the benefit users can perceive, use product terminology rather than implementation terminology (status_code, internal class names, and so on) for scope words, and qualify the scope accurately. For type values and changelog categories, see "Release Process" below and .release-please-config.json.
Release Process
Version numbers and the changelog are maintained automatically by release-please (configuration in .release-please-config.json, workflow in .github/workflows/release-please.yml). Developers do not need to bump version numbers manually—only write compliant conventional commits.
Workflow
- Squash-merge ordinary PRs into
mainaccording to the conventional commits specification; rebase-mergeafk-team-workflowstage PRs as described in the exception above - release-please scans commits since the previous release and automatically opens or updates a Release PR titled like
chore(main): release X.Y.Z, containing the next version number and an updatedCHANGELOG.md - Merging that Release PR automatically creates a
vX.Y.Ztag and publishes a GitHub Release
commit type → version increment
| commit type | Version increment | changelog |
|---|---|---|
feat | minor | ✨ 新功能 |
fix | patch | 🐛 Bug 修复 |
feat! / any type + ! / footer containing BREAKING CHANGE: | major (minor when version <1.0.0) | ⚠️ BREAKING CHANGES (at the top of the changelog) |
perf / refactor / docs / revert | No increment | Shown (⚡ / ♻️ / 📚 / ↩️) |
chore / ci / build / test / style | No increment | Hidden |
By default, only
featandfix(as well as breaking changes) trigger a version bump in release-please. Configuringperf/refactor/docs/revertwithhidden: falseaffects only their presentation in the changelog; it does not make them trigger a patch bump. If an iteration contains only these commit types, no Release PR is produced until the nextfix/featcommit arrives.
The version fields in pyproject.toml and frontend/package.json are maintained automatically by release-please (see the # managed by release-please comment in pyproject.toml) and are read-only for developers. uv.lock is likewise synchronized automatically by uv lock in the release-please workflow on the Release PR branch. The actual version state is defined by the git tag and .release-please-manifest.json.
commit examples
# New feature (minor bump)
feat(image-backends): 支持 OpenAI DALL-E 3 后端
# Bug fix (patch bump)
fix(queue): 修复任务 lease 超时后未正确归还的问题
# With a scope and a body
feat(grid): 支持 grid_12 布局
将多宫格分镜系统扩展到 12 宫格，适用于长篇剧集的批量预览。
This repository does not use breaking-change markers. The frontend and backend are released together from one repository, and the backend API makes no versioned external guarantees—the bundled frontend evolves with each version, while external integrations use /agent-installation-guide.md to find the current installation entry point rather than depending on a version number. Classify API removals and changes normally as fix/refactor; do not add a ! suffix or write a BREAKING CHANGE: footer. Correct an incorrectly marked merge according to its merge method: for an ordinary squash PR, edit the PR body to append a BEGIN_COMMIT_OVERRIDE/END_COMMIT_OVERRIDE block, then wait for the next main push or rerun the workflow manually; for an AFK rebase stage, after the final main push has updated the Release PR, correct its version and changelog artifacts directly, pass the integrity checks, and then merge the Release PR. During the 0.x stage, bump-minor-pre-major only limits the version jump caused by an incorrect marker to minor; it does not correct the changelog.
The following syntax is documented only to help identify incorrect markers. There are two equivalent ways to mark a breaking change:
# Form 1: append ! after the type
feat(api)!: 移除 /api/v1/legacy 端点
# Form 2: a footer containing BREAKING CHANGE (more common; allows a multi-line description)
feat(auth): 统一 API Key 验证逻辑
BREAKING CHANGE: /api/v1/api-keys 的返回结构改为 { items: [...] }，
旧客户端需要适配。
In both forms, release-please will:
- Bump the version number to major; when the current version is <1.0.0, the
bump-minor-pre-majorconfiguration limits this to a minor bump - Insert a separate ⚠️ BREAKING CHANGES section at the top of the changelog, summarizing the description of each breaking change
- Keep the commit's regular entry under the corresponding type section (such as
✨ 新功能)