Files
youtube-generator/CONTRIBUTING.md
T
poli0981andClaude Opus 5.5 5a9e7e83de ci(qodana): add Qodana for TypeScript and Rust
A Qodana workflow with one job per Qodana Cloud project:
- typescript: Qodana for JS in native mode, on the runner's Node 26 and
  node_modules (qodana.yaml, project yt-ts-js, QODANA_TOKEN_TS_JS);
- rust: Qodana for Rust, Early Access, in Docker on src-tauri/
  (src-tauri/qodana.yaml, project yt-rust, QODANA_TOKEN_RUST). Its
  bootstrap installs what rust.yml installs; a stand-in dist/index.html
  lets generate_context!() expand.

Both use qodana.recommended with a quality gate of zero problems and
analyse the whole project on every run. A tokens job skips the analysis
for Dependabot and fork PRs, which get no secrets; the token reaches only
the scan step, never `npm ci`. Annotations and artifacts, no PR comment.
Failures reach Discord through notify-ci-failure.yml.

Docs: TECH-SPEC (workflow table, Qodana notes), DEVELOPMENT (+ vi),
CONTRIBUTING, CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 10:21:18 +07:00

6.5 KiB

Contributing to YTDescGen

Thanks for taking the time to contribute. Read this once before opening your first PR — it saves time on both sides.

Code of Conduct

Participation is governed by the Code of Conduct. By contributing, you agree to its terms.

Getting Started

  1. Read the Development Guide — also available in Vietnamese.
  2. Install dependencies: npm install.
  3. Start the dev server: npm run dev.
  4. Before opening a PR, run the same gates CI runs (the required check job):
    npm run typecheck && npm run typecheck:all
    npm run lint && npm run format:check
    npm run validate:locales
    npm run test:coverage
    npm run knip
    npm run check:version && npm run check:tauri && npm run check:licenses
    npm run check:copyright
    npm run build && npm run check:bundle
    npm run cf:check
    
    check:licenses fails when THIRD_PARTY_NOTICES.md is stale — npm run generate:third-party rewrites it. check:copyright fails in the first commit of a new year — npm run update:copyright fixes it. Touched src-tauri/? Also cargo fmt --check, cargo clippy --all-targets --locked -- -D warnings and cargo test in src-tauri/ (after npm run build — see the Development Guide).

How to Contribute

Issues

Use the templates in .github/ISSUE_TEMPLATE/:

  • Bug report — only if you can reproduce on the latest release.
  • Feature request — only with a concrete use case, not abstract requests.
  • Accessibility barrier — anything that gets in the way with a keyboard, a screen reader, zoom, high contrast, voice control or touch. No reproduction on the latest release needed, and you don't need to know the cause. See ACCESSIBILITY.md.

Pull Requests

  • Branch from main (feat/…, fix/…, docs/…) and open the PR against main. Every merge to main deploys the web app, so main stays releasable.
  • Commit format and PR title: type(scope): message — e.g. feat(engine): add Spanish template support. Types: feat, fix, refactor, docs, test, ci, chore. CI checks the PR title.
  • Required checks: check, dependency-review, workflow-lint, reuse, pr-title. When src-tauri/ changes, the Rust workflow's lint-and-test and cargo-deny run too, and GitHub's CodeQL code scanning runs on every PR. SonarCloud analyses PRs opened from this repository — its quality gate wants A ratings, reviewed security hotspots, at most 3 % duplication and at least 80 % test coverage on new code in the layers Vitest measures (PRs from forks get no secrets and skip it; the maintainer's merge runs it on main). JetBrains Qodana does the same for TypeScript and for the Rust shell, and fails on any problem it finds. Commits on main are signed.
  • PR titles start with a lower-case letter after the colon (feat(editor): add …, not feat(editor): Add …).
  • One logical change per PR. Don't bundle unrelated refactors.
  • All locale files must stay in lock-step — see the i18n section below.
  • AI-assisted contributions are welcome but must be disclosed in the PR description.

Accessibility

UI changes keep YTDescGen usable with the keyboard alone and with screen readers. Run through the checklist in ACCESSIBILITY.md (the PR template repeats it); the contrast test (tests/styles/contrast.test.ts) fails if a colour token drops under WCAG AA.

i18n Contributions

If your change adds or removes any user-facing string:

  1. Update the locale schema at src/i18n/locales/_schema.json first.
  2. Add the key to all 8 locales (en / vi / ja / es / ko / zh / pt-BR / id).
  3. npm run validate:locales must pass.

Native-speaker corrections to AI-translated locales (JA / ES / KO / ZH / PT-BR / ID) are especially welcome — see DISCLAIMER.md for the current translation-quality status.

Auto-ignored Contributions

The following are closed without review and may result in a contributor ban — no exceptions:

  • Suspected malicious code. If a PR contains code we suspect may be a supply-chain attack, obfuscation, credential harvesting, cryptominer, or any form of malware — even if CodeQL and Dependabot don't flag it, the maintainer may investigate manually. Detection equals ban.
  • Unverified or suspicious links in issues, PRs, or comments (pastebin scrapers, redirect chains, unfamiliar shortlinks, link-shortener URLs without context).
  • Behavior or language violating GitHub's Acceptable Use Policies.
  • Off-topic / rambling reports that don't get to the point. Example of what gets ignored: "Good morning, today is a beautiful day, I was just wondering if maybe…" — get straight to the problem.
  • PRs that touch hundreds of files for a one-line fix (typical sign of an auto-formatter run on unrelated files).
  • Tests deleted or skipped to make CI pass.
  • "AI rewrote my entire codebase in a different style" PRs. AI-assisted edits are welcome (disclosed); whole-repo rewrites are not.
  • Spam, drive-by typo fixes that don't address a real issue, and karma-farming PRs.

What We Want

  • Bug fixes with a reproduction case and a regression test.
  • Locale corrections from native speakers.
  • New content-warning or tech-note IDs with all 8 translations and a clear rationale (especially horror-genre vocabulary) — the checks fail until every locale has its label and description line.
  • New video types or genres that fit the gameplay no-commentary use case.
  • Accessibility and mobile-responsive improvements.
  • Performance fixes with a before/after measurement.

What We Don't Want

  • Cosmetic refactors with no behavior change.
  • Adding new runtime dependencies without first opening an issue to discuss the tradeoff.
  • Renaming files without coordinating with open PRs.
  • Changes to the LICENSE or NOTICE files (these are governance, not contributions).

Contact

Questions about contributing or conduct: code@poli0981.dev. Security issues go through SECURITY.md, never a public issue. Accessibility barriers you'd rather not post publicly: contact@poli0981.dev, subject starting with [Accessibility].

License

By contributing, you agree your contribution will be licensed under the Apache License 2.0, the same license as the project, and that you have the right to grant that license.