Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
82 lines (59 loc) · 3.04 KB

CONTRIBUTING.md

File metadata and controls

82 lines (59 loc) · 3.04 KB
Raw

Contributing to tour-of-python

Thanks for your interest in contributing! Follow these steps to get started:

  1. Set up the local development environment (below).
  2. Bug fixes are always welcome — check the issues list.
  3. New to the project? Look for issues labeled good first issue.

Project structure

root/
├── src/
│   ├── pages/            # Astro routes (e.g. tour/variables.astro)
│   ├── layouts/          # shared page layouts
│   ├── components/       # Astro/React components
│   ├── content/           # MDX/content collections (e.g. blog)
│   ├── i18n/
│   │   ├── locales/       # per-language UI strings (en.yml, id.yml)
│   │   └── chapters/<lang>/   # per-language lesson content
│   └── styles/
├── scripts/               # Python tooling for translations
├── makefile                # task runner (dev, build, translations, lint)
└── astro.config.mjs

Fork and branch

  1. Fork the repository and clone your fork.
  2. Create a separate branch per issue/feature — avoid mixing unrelated changes in one branch.

Local setup

This project uses pnpm for the site and Python 3 (+ PyYAML) for the translation tooling.

pnpm install
pnpm dev

The dev server runs at http://localhost:4321.

Using the makefile

make setup                     # install deps + check Python setup
make dev                       # start dev server
make build                     # production build
make lint                      # lint code
make format                    # format code
make validate-translations     # validate all translation files
make new-language LANG=xx      # scaffold a new language
make check-missing LANG=xx     # find missing translation keys for a language
make stats                     # translation coverage stats

Run make help (or just make) for the full command list.

Adding or editing a lesson

Lesson content lives in src/i18n/chapters/<lang>/ and UI strings in src/i18n/locales/<lang>.yml. If you're adding a whole new chapter, use the /new-chapter workflow or check src/pages/tour/ for how existing chapters wire up routing, sidebar, and TOC entries.

Adding a new language

Run make new-language LANG=xx to scaffold the locale file and chapter directory, then fill in translations and run make check-missing LANG=xx / make validate-translations before opening a PR.

Testing your changes

Before pushing, make sure:

  • pnpm build succeeds
  • make validate-translations passes if you touched any i18n content
  • pnpm dev still renders the pages you changed

Submitting a pull request

  1. Commit your changes: git commit -m "<your message>".
  2. Push to your fork: git push origin <your-branch-name>.
  3. Open a pull request against main, describing what changed and why.
  4. Link the issue your PR resolves, if any.

By participating in this project, you agree to abide by the Code of Conduct.