|
1 | 1 | # Contributing |
2 | 2 |
|
3 | | -Thanks for helping people learn Python! The goal is lessons that are **short, correct, kind to beginners and machine-verified**. |
| 3 | +Thanks for helping people learn Python! The goal is lessons that are **short, correct, kind to beginners and machine-verified**. You do not need to be an expert: fixing a confusing sentence is as welcome as writing a lesson. |
| 4 | + |
| 5 | +## Ways to help |
| 6 | + |
| 7 | +- **Report a problem.** Confusing wording, a wrong explanation or a check that rejects a correct answer all count as bugs. Open an issue and name the lesson. |
| 8 | +- **Review a lesson.** Lessons are drafted with AI help and then checked by people. Read one as a beginner and tell us where you got stuck. |
| 9 | +- **Write or improve a lesson.** See below. |
| 10 | +- **Improve the site.** Accessibility, mobile layout and offline use matter here. See [Working on the website](#working-on-the-website). |
| 11 | + |
| 12 | +Look for issues labelled `good first issue`. |
| 13 | + |
| 14 | +## Get set up |
| 15 | + |
| 16 | +You need Python 3.11+ and, for the website, Node 22+. |
| 17 | + |
| 18 | +```bash |
| 19 | +git clone https://github.com/Adutchguy/Learn-Python.git |
| 20 | +cd Learn-Python |
| 21 | +python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1 |
| 22 | +pip install -r requirements.txt -r requirements-tracks.txt |
| 23 | +cd web && npm ci && cd .. |
| 24 | +``` |
| 25 | + |
| 26 | +Confirm everything works before you change anything: |
| 27 | + |
| 28 | +```bash |
| 29 | +python tools/validate_content.py && python tools/check_solutions.py |
| 30 | +``` |
| 31 | + |
| 32 | +## How the repository fits together |
| 33 | + |
| 34 | +| Folder | What it is | Edit it? | |
| 35 | +| --- | --- | --- | |
| 36 | +| `content/` | Every lesson, plus placement, review and fast-track questions. **The single source of truth.** | Yes | |
| 37 | +| `exercises/` | The "work on your own computer" track, generated from `content/`. | No, run `python tools/build_exercises.py` | |
| 38 | +| `web/` | The website (Astro). It reads `content/` directly and runs Python in the browser with Pyodide. | For site changes | |
| 39 | +| `learn/` | The small `python -m learn` command-line helper for the local track. | For CLI changes | |
| 40 | +| `tools/` | Validators, generators and the new-lesson scaffold. | For tooling changes | |
| 41 | +| `docs/` | The plan and the [content style guide](docs/CONTENT-STYLE-GUIDE.md). | Yes | |
4 | 42 |
|
5 | 43 | ## Ground rules |
6 | 44 |
|
7 | | -1. **`content/` is the only place lessons are edited.** `exercises/` is generated; the website reads `content/` directly. |
| 45 | +1. **`content/` is the only place lessons are edited.** `exercises/` is generated. |
8 | 46 | 2. **Every exercise is machine-checked in CI.** The solution must pass its tests and the starter must fail them. |
9 | 47 | 3. **Every `assert` in a lesson test carries a helpful message** that tells the learner what to do, not just that they were wrong. CI enforces this. |
10 | 48 | 4. Follow the [content style guide](docs/CONTENT-STYLE-GUIDE.md) for tone, structure and what the browser runner supports. |
11 | 49 | 5. Claims about current versions, tools or prices should be checked against official sources when written. |
12 | 50 |
|
13 | 51 | ## Adding a lesson |
14 | 52 |
|
15 | | -1. Pick the module folder in `content/` (or create `content/NN-name/module.json` with a `title` and `description`). |
16 | | -2. Create `content/<module>/NN-lesson-name/` containing: |
17 | | - - `lesson.md`: YAML frontmatter plus the lesson text |
18 | | - - `starter.py`: what the learner sees |
19 | | - - `solution.py`: a reference answer |
20 | | - - `test_exercise.py`: pytest-style checks |
| 53 | +Let the scaffold create the files and numbering for you: |
| 54 | + |
| 55 | +```bash |
| 56 | +python tools/new_lesson.py "Sets and frozensets" --module 03-data-structures |
| 57 | +``` |
| 58 | + |
| 59 | +It creates `content/03-data-structures/NN-sets-and-frozensets/` with `lesson.md`, `starter.py`, `solution.py` and `test_exercise.py`, and sets the prerequisite to the previous lesson. Useful options: |
| 60 | + |
| 61 | +| Option | When to use it | |
| 62 | +| --- | --- | |
| 63 | +| `--minutes N` | The lesson takes about N minutes (1 to 60). | |
| 64 | +| `--local-only` | It needs real network, subprocesses or threads, so it cannot run in a browser. | |
| 65 | +| `--packages numpy pandas` | It needs a third-party package (`numpy`, `pandas` or `matplotlib`). | |
| 66 | +| `--new-module "Title"` | Start a new module. Add `--optional` to make it an optional track. | |
| 67 | + |
| 68 | +Then: |
| 69 | + |
| 70 | +1. Replace every placeholder. The validator refuses lessons that still contain the `SCAFFOLD` line, so an unfinished lesson cannot be merged by accident. |
| 71 | +2. Add one or two questions for the lesson to `content/review/questions.json` (see the style guide). You do not work out the answer key by hand: the validator runs each program and tells you the right answer. |
21 | 72 | 3. Run the checks: |
22 | 73 |
|
23 | 74 | ```bash |
24 | 75 | python tools/validate_content.py |
25 | 76 | python tools/build_exercises.py |
26 | 77 | python tools/check_solutions.py |
| 78 | + python -m pytest tools/tests |
27 | 79 | cd web && npm test |
28 | 80 | ``` |
29 | 81 |
|
30 | | -4. Preview it in the browser: `cd web && npm run dev`. |
| 82 | +4. Read your lesson in the browser as a beginner would: `cd web && npm run dev`. |
31 | 83 | 5. Commit **both** `content/` and the regenerated `exercises/` files. |
32 | 84 |
|
| 85 | +### Optional tracks |
| 86 | + |
| 87 | +Data Analysis, Automation and Web & APIs are **optional tracks**: modules whose `module.json` has `"optional": true`. They are not part of the core path, the placement test or the fast track. A core lesson may never require an optional lesson (the validator checks), but a track lesson may build on core lessons. Track lessons that use `numpy`, `pandas` or `matplotlib` declare them in `packages:`. In the browser they are downloaded on first use; locally they come from `requirements-tracks.txt`. |
| 88 | + |
| 89 | +## Working on the website |
| 90 | + |
| 91 | +```bash |
| 92 | +cd web |
| 93 | +npm run dev # live preview |
| 94 | +npm run build # production build, including the offline service worker |
| 95 | +``` |
| 96 | + |
| 97 | +Please keep these in mind; they are the things a visitor on a phone, with a screen reader or without a connection relies on: |
| 98 | + |
| 99 | +- **Accessibility.** Keep the skip link, headings and landmarks; every interactive element needs a visible focus state and a name; never rely on colour alone to show pass or fail. Code and UI colours need at least 4.5:1 contrast in both light and dark mode. Run an [axe](https://github.com/dequelabs/axe-core) audit if you change styles or markup. |
| 100 | +- **Mobile.** The layout must work at 360 px wide with no sideways page scroll, and tap targets should be at least 44 px on touch screens. |
| 101 | +- **Offline.** `web/public/sw.js` is a template: `web/integrations/pwa.mjs` fills in the file list when the site is built. New files in `web/public/` are picked up automatically. Test offline behaviour in a production build (`npm run build && npm run preview`), because the service worker is off in `npm run dev`. |
| 102 | + |
33 | 103 | ## Pull requests |
34 | 104 |
|
35 | 105 | - One lesson or one fix per pull request keeps review quick. |
36 | 106 | - CI must be green. It validates content, checks `exercises/` is up to date, runs every lesson through real pytest *and* through the in-browser runner on real Pyodide, and builds the site. |
37 | 107 | - Explain *why* the lesson teaches things in this order if the ordering is not obvious. |
| 108 | +- The pull request template has a short checklist; please tick it honestly. |
| 109 | + |
| 110 | +## Licensing |
| 111 | + |
| 112 | +By contributing you agree that code is released under the [MIT license](LICENSE) and lesson text under [CC BY-SA 4.0](LICENSE-CONTENT.txt). |
38 | 113 |
|
39 | 114 | ## Reporting problems |
40 | 115 |
|
41 | | -Open an issue and include the lesson name and, if it is a checking problem, the code you wrote. Confusing wording counts as a bug. |
| 116 | +Open an issue and include the lesson name and, if it is a checking problem, the code you wrote. |
0 commit comments