From 8fe81dea18d7ffb01a9b108f5fcacf218fcdb791 Mon Sep 17 00:00:00 2001 From: Alex Shnitman Date: Fri, 17 Jul 2026 15:08:33 +0300 Subject: [PATCH] docs: encode project scope boundary in AGENTS.md Document the line between in-scope work (improving the download-time write, surfacing yt-dlp built-ins) and out-of-scope work (post-download tag editing, external metadata lookups, library organization), so agent-assisted contributions can check their plans against it before writing code. Follows the decisions on #1025, #1026/#1027, #1028, #1031. Co-Authored-By: Claude Fable 5 --- AGENTS.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 4a27f4d..39e5c65 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,53 @@ # Agent Guidelines +## Project scope — read this before planning a feature + +MeTube's contract is: give it a URL, it runs yt-dlp well, and correct files appear. +The maintainer holds a deliberate line on what belongs inside that contract, and PRs +on the wrong side of it are declined **regardless of code quality**. Check your plan +against this line before writing any code. + +**In scope — improving the write itself:** + +- Features that make the file yt-dlp writes at download time come out more correct, + using only data the extractor already provides (e.g. filling a missing album-artist + tag from the extractor's own metadata). +- Surfacing functionality yt-dlp itself owns and maintains as first-class UI options + (e.g. a SponsorBlock toggle that just passes yt-dlp postprocessor params). +- Download queue, subscriptions, output templates, and UI improvements to the + download workflow. + +**Out of scope — managing files after they exist:** + +- Tag editors, metadata dialogs, or any workflow that rewrites files after the + download has finished. This holds even for slimmed-down versions. +- Lookups against external metadata services (iTunes, Deezer, MusicBrainz, etc.). + More broadly: any new dependency on a third-party API, or new network egress from + self-hosted instances, beyond what yt-dlp itself performs. +- Library organization: moving/renaming existing files into Artist/Album layouts, + watch-folder processing, and similar media-manager features. Dedicated tools + (beets, MusicBrainz Picard, Lidarr) do this properly; the README points users + to them. + +**Corollaries that shape borderline PRs:** + +- Site-specific intelligence (parsing playlist-ID prefixes, URL path conventions, + and other platform internals) is extractor work and belongs upstream in yt-dlp, + not re-implemented here — it silently breaks when the platform changes and + MeTube would own the breakage. +- Prefer enriching yt-dlp's info dict and letting its existing pipeline + (FFmpegMetadata etc.) do the writing, over adding custom per-format tag-writing + code to MeTube. +- Supplemental processing must never fail a download that otherwise succeeded: + warn and continue, don't raise. +- Keep feature scope minimal on first submission. A hardcoded sensible default + beats a configuration surface; follow-ups can add options when users actually + ask. PRs that bundle several "reasonable next steps" invite rejection of the + whole. + +If a feature idea fails this test, the accepted alternative is usually a README +section documenting how to pair MeTube with the right dedicated tool. + ## README.md size constraint The README.md is synced to Docker Hub, which has a **25,000 character limit**.