|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## Purpose: Pull Request validation |
| 4 | + |
| 5 | +This repository is public. |
| 6 | + |
| 7 | +These instructions are intended for implementing and maintaining automated Pull Request validation for TDTChannels using GitHub Actions and small supporting scripts. |
| 8 | + |
| 9 | +The main catalog files are: |
| 10 | + |
| 11 | +* `TELEVISION.md` |
| 12 | +* `RADIO.md` |
| 13 | + |
| 14 | +Contributions must follow `CONTRIBUTING.md`. |
| 15 | + |
| 16 | +## Required reading |
| 17 | + |
| 18 | +Before changing validation logic: |
| 19 | + |
| 20 | +1. Read `CONTRIBUTING.md`. |
| 21 | +2. Inspect the real structure of `TELEVISION.md` and `RADIO.md`. |
| 22 | +3. Review representative entries and legitimate historical exceptions. |
| 23 | +4. Check the existing workflows under `.github/workflows/`. |
| 24 | + |
| 25 | +Do not assume the catalog is perfectly uniform and do not rewrite catalog data merely to simplify validation. |
| 26 | + |
| 27 | +## Implementation guidelines |
| 28 | + |
| 29 | +* Keep changes focused on Pull Request validation. |
| 30 | +* Do not refactor unrelated files. |
| 31 | +* Prefer small, maintainable, and testable implementations. |
| 32 | +* Prefer the Python standard library unless a dependency clearly improves correctness. |
| 33 | +* Add or update tests for behavioral changes. |
| 34 | +* Run all relevant tests before finishing. |
| 35 | +* Report repository-specific exceptions, ambiguities, and known limitations. |
| 36 | + |
| 37 | +## Validation behavior |
| 38 | + |
| 39 | +* Validate only added or modified catalog entries whenever possible. |
| 40 | +* Load the full catalog only when required, such as for duplicate detection. |
| 41 | +* Favor low false-positive rates over aggressive blocking. |
| 42 | +* Keep deterministic validation separate from network availability checks. |
| 43 | +* Network checks must always be advisory because GitHub-hosted runners may execute outside Spain and many streams are geo-restricted. |
| 44 | +* Do not download video or audio segments unless explicitly requested. |
| 45 | +* Use `GET`, follow redirects, apply short timeouts and response-size limits, and use an identifiable User-Agent. |
| 46 | +* Do not treat `Content-Type` as definitive proof of the response format. |
| 47 | + |
| 48 | +## GitHub Actions |
| 49 | + |
| 50 | +* Use standard GitHub-hosted runners. |
| 51 | +* Support Pull Requests from forks. |
| 52 | +* Prefer workflows that require no secrets. |
| 53 | +* Use minimum permissions. |
| 54 | +* Do not add write permissions solely to post comments. |
| 55 | +* Add sensible job timeouts and cancel obsolete runs where appropriate. |
| 56 | +* Do not add automatic approval or automatic merge. |
| 57 | + |
| 58 | +## Public repository and secrets |
| 59 | + |
| 60 | +Treat repository files, Git history, Pull Requests, workflow logs, fixtures, artifacts, and comments as publicly visible. |
| 61 | + |
| 62 | +* Never commit, generate, paste, or expose credentials, tokens, passwords, API keys, private keys, cookies, signed URLs, session identifiers, or other sensitive values. |
| 63 | +* Do not print secrets, authorization headers, cookies, or environment variables in logs. |
| 64 | +* Use clearly fake placeholders or environment-variable references in tests and examples. |
| 65 | +* Do not commit `.env` files. |
| 66 | +* If credentials appear to be required, stop and report the requirement instead of adding them. |
| 67 | +* If sensitive information is discovered, do not reproduce it. Report its location and recommend revocation and removal. |
| 68 | + |
| 69 | +## Legal and compliance boundaries |
| 70 | + |
| 71 | +* Only use streams and sources publicly and legitimately exposed by their official broadcaster or distributor. |
| 72 | +* Do not add or facilitate access to unauthorized, private, pirated, paywalled, or unlawfully redistributed streams. |
| 73 | +* Do not bypass authentication, DRM, geoblocking, access controls, anti-bot protections, or other technical restrictions. |
| 74 | +* Do not extract hidden streams, forge authorization data, reuse private tokens, or impersonate official clients. |
| 75 | +* Flag unclear authorization or official origin for human review. |
| 76 | + |
| 77 | +## Scope |
| 78 | + |
| 79 | +Unless explicitly requested: |
| 80 | + |
| 81 | +* Do not add AI validation, paid APIs, or external infrastructure. |
| 82 | +* Do not modify contributor submissions automatically. |
| 83 | +* Do not post automatic Pull Request comments. |
| 84 | +* Do not merge changes. |
| 85 | +* Leave changes ready for human review. |
0 commit comments