# Contributing to FlyPython FlyPython maintains bilingual Python engineering guides, task playbooks, runnable examples, templates, and a reviewed source catalog used by [flypython.com](https://flypython.com/). Contributions should help a visitor complete a real Python task or improve factual accuracy and maintainability. General Python questions belong in [GitHub Discussions](https://github.com/flypythoncom/python/discussions). Read the [curation policy](docs/CURATION_POLICY.md) before contributing. ## Permissions This repository is dual-licensed as described in [LICENSE](LICENSE): code (examples, tools, templates, course starters/solutions/verifiers) under the MIT License, and written content (guides, playbooks, lessons, catalog records, READMEs) under CC BY 4.0 with attribution "FlyPython (flypython.com)". Contributors must submit only material they have the right to submit and retain required third-party notices; a file's own license header, when present, wins. ## Propose a change Use the matching issue form before a larger change: - **Resource proposal** for a new official source. - **Project proposal** for a current Python project that should receive human review for Project Radar. - **Course feedback** for running a course or reporting a course problem. - **Broken link** for an unreachable or replaced resource. - **Security report** for a vulnerability; follow [SECURITY.md](SECURITY.md) instead of opening a public issue. Small typo, metadata, or tooling fixes may go directly to a focused pull request. First-party guides and playbooks must remain practical, testable, and aligned in English and Chinese. A content change must update both language files with the same content version and review date, then regenerate `content-manifest.json`. Do not present generated code, a passing test, or a deployment command as proof of user value or production readiness. ## Catalog sources The canonical source is the `catalog/` directory: - `catalog/catalog.yml` contains catalog-level review state. - `catalog/paths.yml` defines the four bilingual learning paths. - `catalog/resources/.yml` contains one reviewed resource. - `catalog.json` is generated output and must not be edited by hand. Every resource file must include: - `id`, `path`, `order`, `title`, and `url` - `source_type`, `level`, and `language` - `why_en` and `why_zh` - `reviewed_on` and `status` - `requires_key`, `risk`, and `featured` The filename must match the stable resource ID. Resource `order` values must be unique and consecutive within each path. Descriptions and classifications require human review. Do not use an LLM or a web-search API to generate them. Prefer official documentation, official standards, and official project pages. A 403, 429, timeout, or transient 5xx response is not enough to delete a resource. Mark it for human review and provide repeatable evidence. ## Local setup Install the exact Python version from `.python-version` and the locked development dependencies: ```bash python -m venv .venv . .venv/bin/activate python -m pip install -r requirements-dev.lock.txt ``` After changing catalog sources, regenerate the public export: ```bash python tools/export_catalog.py python tools/render_readmes.py python tools/build_content_manifest.py ``` Run the same deterministic checks as CI: ```bash python -m pytest python tools/validate_catalog.py python tools/export_catalog.py --check --target both python tools/render_readmes.py --check python tools/build_content_manifest.py --check python tools/verify_examples.py python tools/verify_courses.py python tools/verify_paths.py ``` Maintainers can run the networked link audit through GitHub Actions. For a deliberate local audit of every catalog entry: ```bash python tools/check_links.py --mode all --output reports/link-check.json ``` Network fetching is excluded from pull-request CI. Any review-needed result fails the scheduled audit for maintainer inspection, but does not by itself justify removing a resource. ## Pull request checklist - Keep source content and generated JSON exports consistent. - Preserve English and Chinese meaning. - Include evidence for maintenance, ownership, access, and safety claims. - Do not call a project production-ready without current evidence. - Do not commit secrets, generated reports, caches, or local environments. - Explain consumer-visible changes and list the validation results. Passing automation does not replace editorial review. After merge, a website consumer must deliberately update its pinned catalog commit before the new data appears on flypython.com. ## Release and tag rules - A pushed tag is **immutable**: never delete, move, or reuse it. `v0.1.0` stays pointed at its original commit forever. - This repository and the website (`flypythoncom/flypython.com`) are independent release artifacts. They may ship different version numbers in the same release train; the compatibility mapping is recorded in both CHANGELOGs and in the GitHub Releases (e.g. website `v0.1.0` ↔ repository `v0.1.1`), each naming the exact commit SHA. - The website consumes this repository at a pinned full commit SHA (`content-pin.json`) — never a moving branch or tag. - `pyproject.toml` `version` tracks the repository release; bump it in the change that cuts the release.