Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
117 lines (87 loc) · 4.21 KB

CONTRIBUTING.md

File metadata and controls

117 lines (87 loc) · 4.21 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 currently does not grant a general license to reuse its content or code. Public visibility is not permission to copy, redistribute, or relicense repository material. Contributors must submit only material they have the right to submit and retain required third-party notices.

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.
  • 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
python tools/render_readmes.py --check
python tools/build_content_manifest.py --check
python tools/verify_examples.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.