Contributing

Contributions are very welcome; please contact us by email or by filing an issue in our repository. All contributors must abide by our Code of Conduct.

Setup

Install uv.
Create a virtual environment by running uv venv in the root directory.
Activate it by running source .venv/bin/activate in your shell.
Install dependencies by running uv pip install -r pyproject.toml.

Operation

Run make in the root directory to display operations:
- make commands: show available commands
- make clean: clean up
- make build: regenerate HTML in ./docs
- make lint: check code and project
- make serve: serve generated HTML
- make stats: basic site statistics
See the Run section of each lesson's index.md file for more specific instructions.

Contributions

Please use Conventional Commits style for pull requests by using feature:, fix:, or refactor: as the first word in the title of the commit message.

Notes

Each lesson has a static directory lesson-specific files needed by the browser. Each static directory also has a symbolic link to the shared directory in the project root, which contains files shared between lessons. This pattern allows us to configure a single static path in Flask and then refer to lesson-specific files as /static/whatever and shared static files as /static/shared/whatever. Thanks to __init__.py files in shared and each static directory, it also allows us to import static.shared.whatever in Python.

FAQ

Do you need any help?: Yes: please see the issues in our repository.
What sort of feedback would be useful?: Everything is welcome, from pointing out mistakes in the code to suggesting better examples or explanations.
Can I add a new section?: Probably: please reach out before doing so.
Why is this material free to read?: Because if we all give a little, we all get a lot.

Contributors

Greg Wilson is a programmer, author, and educator based in Toronto. He was the co-founder and first Executive Director of Software Carpentry and received ACM SIGSOFT's Influential Educator Award in 2020.