From c7c138ad97ec255250e3060a875034b77055d384 Mon Sep 17 00:00:00 2001 From: Michel Wermelinger Date: Sat, 6 Jan 2024 13:37:41 +0000 Subject: [PATCH] Update installation and contribution docs --- CONTRIBUTING.md | 78 ++++++++++++++++++++++++++++++++----------------- README.md | 46 ++++++++++++++++++++++++----- 2 files changed, 89 insertions(+), 35 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 803e7f4..8156bd6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,34 @@ # Contributing -This file documents how the library is developed, in case you want to contribute. - -By contributing code or documentation to this repository, -you agree to transfer the copyright of your contribution to The Open University, UK, -and that your contribution will be subject to the `paddles` [licence](README.md#Licence). - -## Environment +This document explains how the library is developed, +in case you want to contribute code or documentation. To contribute, you need: +- an IDE, e.g. Visual Studio Code or PyCharm +- a [GitHub account](https://docs.github.com/en/get-started/quickstart/creating-an-account-on-github) + (we recommend using your academic email, to get education benefits) +- a basic knowledge of GitHub + (see this [tutorial](https://docs.github.com/en/get-started/quickstart/hello-world)) +- a basic knowledge of [Markdown](https://www.markdownguide.org/cheat-sheet/), to write docstrings +- software to send your contributions back to GitHub, like [git](https://git-scm.com) (if you prefer the command line) + or [GitHub Desktop](https://desktop.github.com/) (if you prefer a more user-friendly app) + +You may wish to first read the more detailed and beginner-friendly +[contribution guide for `allowed`](https://github.com/dsa-ou/allowed/blob/main/docs/contribution.md), +as much of it also applies to `paddles`. + +## Development environment We use Python 3.10 and the [poetry](https://python-poetry.org) packaging and dependency manager. -To set up the environment: -- if you don't have Python 3.10, [install it](https://www.python.org/downloads/release/python-31011/) -- if you don't have `poetry`, [install it](https://python-poetry.org/docs/#installing-with-the-official-installer) -- clone this repository -- open a terminal and go to the folder to where you cloned this project -- enter `poetry install` - -This installs the software needed to develop `paddles`, in a new +We use an older Python version for development to make sure `paddles` works with it. + +To set up the development environment: +1. if you don't have Python 3.10, [install it](https://www.python.org/downloads/release/python-31011/) +2. if you don't have `poetry`, [install it](https://python-poetry.org/docs/#installing-with-the-official-installer) +3. [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) + this repository (this creates a copy in *your* GitHub account) +4. [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) + your forked repository (this makes a local copy on your machine) +5. open a terminal and go to the folder to where you cloned this project +6. enter `poetry install` + +The last steps installs the software needed to develop `paddles`, in a new [virtual environment](https://docs.python.org/3/glossary.html#term-virtual-environment), in order to not interfere with your existing Python projects. @@ -22,7 +36,7 @@ To use the environment, while developing `paddles`, enter `poetry run C` to execute command `C` in the virtual environment for `paddles`. Alternatively, you can enter `poetry shell` to activate the environment, and -then you can just enter `C` to execute the command. +then just enter `C` to execute the command. To deactivate the environment, enter `exit`. In the rest of this document, the notation `[poetry run] C` means that you should enter @@ -31,19 +45,24 @@ In the rest of this document, the notation `[poetry run] C` means that you shoul To finish the setup, you may optionally enter `[poetry run] pre-commit install` to install pre-commit hooks (scripts that are run when committing changes to a repository). -Our environment has configured hooks that test, check and format your code and +Our development environment includes hooks that test, check and format your code and generate the documentation before you commit your changes to the repository. -This project folder contains the following files and subfolders: +## Structure +The project folder contains the following files and subfolders, among others: -- `README.md`: this file +- `README.md`: an introduction to the project, in Markdown format +- `CONTRIBUTING.md`: this file - `LICENSE`: the code licence - `pyproject.toml`: project configuration - `poetry.lock`: list of the packages installed by `poetry install` - `.pre-commit-config.yaml`: list of pre-commit hooks - `paddles/`: subfolder with the library's code - `tests/`: subfolder with the test code -- `docs/`: subfolder with the documentation generated from the library code +- `docs/`: subfolder with the HTML files of the [documentation site](https://dsa-ou.github.io/paddles). + +The documentation is generated from the docstrings in the code, so do *not* +edit the `docs/` files directly. ## Testing @@ -77,10 +96,10 @@ We check and format all code (library and tests) with [ruff](https://astral.sh/r To check the code against over 700 style rules, enter `[poetry run] ruff check`. If `ruff` reports rule violations, open the [rules page](https://docs.astral.sh/ruff/rules), -search for the reported rule number (e.g. E101), and click on the rule name -(e.g. mixed-spaces-and-tabs) next to it in the page. -This will open a new page explaining the violated rule and its rationale, with an example, -like [this](https://docs.astral.sh/ruff/rules/mixed-spaces-and-tabs/). +search for the reported rule number (e.g. E713), and click on the rule name +(e.g. not-in-test) next to it in the page. +This will open a new page explaining the violated rule with an example, +like [this](https://docs.astral.sh/ruff/rules/not-in-test/). To automatically fix violations, when possible, enter `[poetry run] ruff check --fix --unsafe-fixes` and double-check @@ -109,15 +128,20 @@ to open a live site with the documentation. Any changes to the docstrings of the library files are immediately reflected in the site, upon saving the files. ## Comitting -If you installed the pre-commit hooks when setting up the [environment](#environment) -then every time you commit your code, -these steps are done automatically on the _staged_ files: +If you installed the pre-commit hooks when setting up the development environment, +then every time you commit your code, these steps are done automatically: 1. test the code with `pytest` 2. type check the code with `pytype` 3. check (but _don't_ fix) the code with `ruff` 4. format the code with `ruff` 5. generate the documentation with `pdoc`. +You can therefore just commit whenever you want to check your changes, +instead of running each check manually, as explained in the previous sections. + +The automated steps are executed on the staged files. If you changed some files +but didn't stage them, you will get a warning that those files weren't processed. + If a test or check fails in steps 1–3 or if a file is modified in steps 4–5, then the commit doesn't go ahead. This allows you to review the errors and the automatically applied changes, diff --git a/README.md b/README.md index 07479b1..e0e8221 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,47 @@ - be easy to install, use and understand - adhere to good Python coding practices. -To install the library, type `pip install paddles` at the command line, -preferably after activating a virtual environment. -Your default Python version must be 3.10 or later. +`paddles` is a work in progress. +The current version 0.1 implements stacks, queues and deques. -This is version 0.1 of the library. It is a work in progress. -It currently implements the Stack, Queue and Deque abstract data types (ADTs). +## Usage +To use `paddles`, follow these steps: -The code repository is at https://github.com/dsa-ou/paddles. -The formatted documentation is at https://dsa-ou.github.io/paddles. +1. Open a terminal and enter `python -V` to get your Python's version. + If the version is 3.10 or higher, go directly to step 3. +2. If the version is lower than 3.10 or if you get an error message + ('`python` is an unknown command' or similar), then close the terminal and + install the [latest Python version](https://www.python.org/downloads/). +3. In the same terminal as step 1, or a new one if you did step 2, + enter `pip install paddles`. +4. To check that the library is now available, enter `python -m paddles.stack`. + You should not get any error message. -## Licence +If you have any problems during installation, please report them in the +[Q & A discussion forum](https://github.com/dsa-ou/paddles/discussions/categories/q-a). +(If you're an M269 student or tutor you can use the Technical Forum instead.) +Don't forget to indicate your operating system, your Python version, +and what you did before the problem occurred, so that we can help you more effectively. + +5. Read the [documentation](https://dsa-ou.github.io/paddles) to learn how to + use the data structures and algorithms provided by `paddles`. + +## Contributing + +Any help to improve and extend `paddles` is welcome and appreciated. + +- If you're an M269 student or tutor, you can report errors and suggest improvements + in the Technical Forum instead of using GitHub's forums and issue tracker. +- If you require a new feature, please suggest it in the + [ideas discussion forum](https://github.com/dsa-ou/paddles/discussions/categories/ideas). +- If you spot an error or omission in the code or documentation, please check if it + [has been reported](https://github.com/dsa-ou/paddles/issues), before creating a new issue. +- If you want to contribute code or documentation that addresses + an [open issue](https://github.com/dsa-ou/paddles/issues), please read first our + [contribution guide](https://github.com/dsa-ou/paddles/blob/main/CONTRIBUTING.md). + Your contribution will become available under the terms below. + +## Licences `paddles` is Copyright © 2024 by The Open University, UK. The code is licensed under a [BSD 3-clause licence](https://github.com/dsa-ou/paddles/blob/main/LICENSE).