Development

Development

Contributor guide for working on the codebase, local tooling, tests, and docs workflow.

---

Repository Layout

yt-study/
  .github/
  scripts/
    hooks/
  src/yt_study/
    cli.py
    setup_wizard.py
    core/
      config.py
      pipeline.py
      llm/
      prompts/
      youtube/
    ui/
      dashboard.py
  tests/
  wiki/
  Makefile
  pyproject.toml
  .pre-commit-config.yaml

Quick Setup

Clone and initialize the wiki submodule:

git clone https://github.com/whoisjayd/yt-study.git
cd yt-study
git submodule update --init --recursive

Install dependencies:

make sync

Install hooks:

make hooks-install

Tooling Stack

Tool	Role
uv	dependency management and command runner
hatchling	builds
pytest	test execution
pytest-asyncio	async test support
ruff	formatting and linting
mypy	type checking
bandit	security scanning
deptry	dependency hygiene
pre-commit	local Git hook orchestration

Common Commands

Command	Purpose
make sync	install locked dependencies
make quick	fast validation
make ci	CI-equivalent validation
make verify	autofix + full quality pass
make test-cov	coverage run
make help	full target list

Architectural Rules

Keep core/ UI-free

Do not import Rich, console rendering, or dashboard code into src/yt_study/core/.

Keep blocking network I/O off the event loop

pytubefix and youtube-transcript-api calls are blocking and must stay behind asyncio.to_thread(...).

Preserve event-driven boundaries

CorePipeline reports progress through PipelineEvent; the CLI is responsible for converting events into UI updates.

Respect config invariants

If you add a provider key, update:

• Config.ALLOWED_KEYS
• Config.get_api_key_name_for_model()
• Config._sync_env_vars()

Keep docs grounded in implemented behavior

Do not document keys, paths, or options that do not exist in the code.

---

Test Layout

Location	Focus
tests/test_cli.py	CLI command behavior
tests/test_config.py	config parsing and env overrides
tests/test_setup_wizard.py	wizard prompt/save flow
tests/test_ui.py	dashboard rendering and state
tests/test_llm/	generator and provider behavior
tests/test_pipeline/	orchestration and event emission
tests/test_youtube/	parser, transcript, metadata, playlist behavior

Documentation Workflow

The wiki/ directory is a Git submodule. Documentation work may touch:

• root docs such as README.md, CONTRIBUTING.md, and AGENTS.md
• wiki pages inside wiki/

When adding a wiki page:

1. create the page inside wiki/
2. link it from wiki/Home.md
3. update the README docs map if it belongs in the public docs surface

Git Hooks

Configured through .pre-commit-config.yaml:

• repo hygiene checks
• Ruff formatting and linting
• Bandit
• mypy
• deptry
• pytest on pre-push
• conventional commit checks
• single-line commit message enforcement via scripts/hooks/check-single-line-commit.sh

Run them manually:

make hooks-run

CI and Release

Current workflows:

• ci-main.yml: validation plus test matrix
• pr-gate.yml: PR checks
• release.yml: validate, build, publish to PyPI, create GitHub release

The PR template expects:

• local make ci
• tests updated where appropriate
• docs updated for behavior or workflow changes

Manual Testing Ideas

• run yt-study setup --force
• process a known public video
• process a playlist
• process a batch file with comments and blank lines
• verify both standard output and chapter-mode output paths
• inspect logs under ~/.yt-study/logs