|
| 1 | +# Contributing to learn.python |
| 2 | + |
| 3 | +Thanks for your interest in improving this curriculum. Whether you are fixing a typo, reporting a broken test, or proposing a new project, your contribution helps every learner who comes after you. |
| 4 | + |
| 5 | +## How to Report Issues |
| 6 | + |
| 7 | +Use the [issue templates](https://github.com/travisjneuman/learn.python/issues/new/choose) to report: |
| 8 | + |
| 9 | +- **Bug reports** — broken links, failing tests, code errors |
| 10 | +- **Feature requests** — new projects, modules, or curriculum improvements |
| 11 | +- **Curriculum feedback** — unclear explanations, typos, suggested rewrites |
| 12 | + |
| 13 | +## How to Submit a Pull Request |
| 14 | + |
| 15 | +1. Fork the repository |
| 16 | +2. Create a branch from `main` (`git checkout -b your-branch-name`) |
| 17 | +3. Make your changes |
| 18 | +4. Run tests if applicable (`python -m pytest`) |
| 19 | +5. Open a pull request against `main` |
| 20 | + |
| 21 | +Keep pull requests focused. One fix or one feature per PR is easier to review than a grab bag of changes. |
| 22 | + |
| 23 | +## Code Style |
| 24 | + |
| 25 | +This is an educational repository. Writing style matters as much as code style. |
| 26 | + |
| 27 | +- **Plain language first.** Explain concepts the way you would to a friend who has never coded. |
| 28 | +- **Hands-on before theory.** Show the code, then explain why it works. |
| 29 | +- **No jargon without explanation.** If you use a technical term, define it on first use. |
| 30 | +- **Python code** should pass `ruff check` and `black --check`. |
| 31 | + |
| 32 | +## Project Structure Conventions |
| 33 | + |
| 34 | +Follow the existing structure for the level you are contributing to: |
| 35 | + |
| 36 | +**level-00 (Absolute Beginner)** |
| 37 | +``` |
| 38 | +project-name/ |
| 39 | + exercise.py |
| 40 | + TRY_THIS.md |
| 41 | +``` |
| 42 | + |
| 43 | +**level-0 through level-10 and expansion modules** |
| 44 | +``` |
| 45 | +project-name/ |
| 46 | + README.md |
| 47 | + project.py |
| 48 | + tests/ |
| 49 | + notes.md |
| 50 | +``` |
| 51 | + |
| 52 | +## Testing Expectations |
| 53 | + |
| 54 | +- Projects from Level 0 onward should include pytest tests in a `tests/` directory. |
| 55 | +- Tests should verify actual behavior, not hard-code expected outputs. |
| 56 | +- Run `python -m pytest tests/` from the project directory to confirm tests pass. |
| 57 | + |
| 58 | +## Curriculum Consistency |
| 59 | + |
| 60 | +- Follow the existing level sequence. Do not introduce concepts out of order. |
| 61 | +- Match the format of neighboring documents and projects. |
| 62 | +- Every document should have navigation links (Previous / Home / Next) at the bottom. |
| 63 | +- New projects should include a README explaining what the learner builds and why. |
| 64 | + |
| 65 | +## Questions? |
| 66 | + |
| 67 | +Open an issue. There are no silly questions in a learning repo. |
0 commit comments