Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
86 lines (63 loc) · 3.51 KB

CONTRIBUTING.md

File metadata and controls

86 lines (63 loc) · 3.51 KB

Contributing

Thank you for your interest in improving this course. Contributions of all kinds are welcome -- fixing typos, improving explanations, adding exercises, or writing new modules.

How to Contribute

  1. Fork the repository
  2. Create a branch for your changes (git checkout -b improve-module-05)
  3. Make your changes
  4. Test that all code examples run correctly
  5. Submit a pull request with a clear description of what you changed and why

Content Guidelines

Writing Style

  • Plain English first. Explain concepts in everyday language before introducing technical terms.
  • Show, do not tell. Every concept should have a runnable code example.
  • Be precise. "Fast" is vague. "O(1) lookup" is precise.
  • Use British English for prose (colour, behaviour, organised). Code uses standard Python conventions.

Code Examples

  • Every code example must be complete and runnable on its own. No fragments that cannot execute.
  • Use realistic variable names and scenarios, not foo and bar.
  • Include comments only where the code is not self-explanatory.
  • Target Python 3.14+ syntax.

Exercises

  • Each module should have 3-5 exercises graduated by difficulty:
    • Practice (1-2): Direct application of one concept
    • Challenge (1-2): Combine multiple concepts, require planning
    • Extension (1): Open-ended, connects to real-world problems
  • Use <details> tags for hints so learners can choose when to peek.
  • Solutions should include commentary explaining the reasoning, not just the code.

Starter File Scaffolding

Starter files should help learners begin, but they should not become hidden walkthroughs.

  • Early modules: be explicit. Show input/output, example sessions, and the obvious next step.
  • Middle modules: show intended usage and expected result shape, but leave the implementation approach to the learner.
  • Late modules: show one realistic demo path or interface example, with fewer process hints and less narration.

Use these patterns consistently:

  • Function exercises: 2-3 example calls and expected outputs.
  • Class exercises: create instances, call key methods, print one or two results.
  • Data-structure exercises: show a short sequence of operations in order.
  • API/database exercises: show one happy path and one edge or error path.
  • Design exercises: show scenario prompts and output format, not pseudo-solutions.

Maintainer checklist:

  • Does main() show intended usage?
  • Does the learner know the output or result shape to expect?
  • Does the file avoid leaking implementation?
  • Is the help level appropriate for the module stage?
  • Is the starter file doing something different from exercises.md?

Module Structure

Follow the standard format defined in the root README:

  1. Introduction
  2. Prerequisites
  3. Learning Objectives
  4. Concepts (with code examples)
  5. Worked Examples
  6. Exercises
  7. Key Takeaways
  8. Further Reading

What Makes a Good Contribution

  • Fixes a factual error or clarifies a confusing explanation
  • Adds a practical exercise with a well-written solution
  • Improves accessibility (better explanations, alternative approaches)
  • Adds content to a planned but unwritten module that fits the existing course structure

What to Avoid

  • Do not add content that requires paid tools or services
  • Do not add framework-specific content beyond what the curriculum covers
  • Do not change the module numbering or part structure without discussion
  • Do not add content that only applies to a specific operating system without noting it