Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
136 lines (104 loc) · 5.22 KB

CONTRIBUTING.md

File metadata and controls

136 lines (104 loc) · 5.22 KB
Raw

Contributing to FlyPython

FlyPython maintains bilingual Python engineering guides, task playbooks, runnable examples, templates, and a reviewed source catalog used by 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.

Read the curation policy before contributing.

Permissions

This repository is dual-licensed as described in 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 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/<id>.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:

python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.lock.txt

After changing catalog sources, regenerate the public export:

python tools/export_catalog.py
python tools/render_readmes.py
python tools/build_content_manifest.py

Run the same deterministic checks as CI:

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:

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.