rahix/openflexure-microscope-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Apply suggestions from code review of branch update-readme-and-contributing

Browse source 
Co-authored-by: Joe Knapper <joe.knapper@glasgow.ac.uk>
This commit is contained in:
Julian Stirling 2025-07-11 16:14:03 +00:00
parent 08aaaa6fe1
commit cef3c9f40d
1 changed files with 12 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

24
CONTRIBUTING.md
View file

@ -2,17 +2,17 @@
All contributions to the OpenFlexure project should follow our [project contributions guidelines](https://openflexure.org/contribute). All contributions to the OpenFlexure project should follow our [project contributions guidelines](https://openflexure.org/contribute).
Any contributions to this repository should follow [our code of conduct](https://openflexure.org/conduct). Any contributions to any of our projects should follow [our code of conduct](https://openflexure.org/conduct).
If you are interested in contributing to the OpenFlexure project and do not know where to start we recommend you visit [our forum](https://openflexure.discourse.group/). If you are interested in contributing to the OpenFlexure project, and do not know where to start, we recommend you visit [our forum](https://openflexure.discourse.group/).
**The rest of this page details contribution guidelines that are specific to this repository.** **The rest of this page details contribution guidelines that are specific to this repository.**
This page generally focusses on the the server not the front-end webapp. For more details on the webapp development see the [webapp's README](./webapp/README.md). This page generally focusses on the back-end of the server, not the front-end webapp. For more details on the webapp development see the [webapp's README](./webapp/README.md).
## Python Development ## Python Development
For installation see the [project README](./README.md). For installation, see the [project README](./README.md).
### Core packages and concepts ### Core packages and concepts
@ -32,20 +32,20 @@ The project also makes use of the following libraries:
## Programming style ## Programming style
Ideally python code should be: Ideally, python code should be:
* Broken up into small clear testable functions. * Broken up into small, clear, testable functions.
* Documented with docstrings (For conventions see below). * Documented with docstrings (For conventions see below).
* Type hinted * Type hinted
* Covered by unit tests (using [pytest](https://docs.pytest.org)) * Covered by unit tests (using [pytest](https://docs.pytest.org))
The server code is going through significant flux during the transition from v2 to v3, so currently our test coverage is being rebuilt and type checking does not yet pass. The server code is going through significant flux during the transition from v2 to v3, so currently our test coverage is being rebuilt and type checking does not yet pass.
[Ruff](https://docs.astral.sh/ruff/) is used both for linting and formatting, the codebase. Our custom linter rules are in out `pyproject.toml`. As we improve the codebase more rules are being added to the linter, see `ruff-increased-checking.toml` for checks that we plan to get passing. [Ruff](https://docs.astral.sh/ruff/) is used both for linting and formatting the codebase. Our custom linter rules are in our `pyproject.toml`. As we improve the codebase, more rules are being added to the linter; see `ruff-increased-checking.toml` for checks that we plan to get passing.
Run `ruff format` to format the code in a way that will pass on our CI. Run `ruff format` to format the code in a way that will pass on our CI.
Run `ruff check` to check for linter errors. Run `ruff check` to check for linter errors. Any contributions that don't pass both of these checks will be automatically rejected by our pipeline.
To check your code before each commit we recommend putting the following script in tour `.git/hooks` directory with the filename `pre-commit`. To check your code before each commit we recommend putting the following script in tour `.git/hooks` directory with the filename `pre-commit`.
@ -71,7 +71,7 @@ ruff check
## Docstrings conventions. ## Docstrings conventions.
For docstrings we write docstrings in [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), and process them with [pydoctor](https://pydoctor.readthedocs.io/). We write docstrings in [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), and process them with [pydoctor](https://pydoctor.readthedocs.io/).
For function arguments, return values, and exceptions we use the following style recognised by reStructuredText: For function arguments, return values, and exceptions we use the following style recognised by reStructuredText:
@ -85,11 +85,11 @@ def a_function(arg1: str, arg2: int) -> tuple[float, int]:
When referring to ``code`` in reStructuredText used double backticks When referring to ``code`` in reStructuredText used double backticks
:param arg1: This is the first argument, we can say everything we need to about it. :param arg1: This is the first argument, we can say everything we need to about it.
If the text wrapas ont a new line this line is indented. If the text wraps onto a new line, this line is indented.
:param arg2: This is the second argument. :param arg2: This is the second argument.
:returns: Say what it returns without anything within the colons. If returning :returns: Say what it returns without anything within the colons. If returning
multiple values a bulleted list is a good idea just make sure: multiple values, a bulleted list is a good idea - just make sure:
* It is indented to 1 level in * It is indented to 1 level in
* There is a blank line before the bullets * There is a blank line before the bullets
@ -97,6 +97,6 @@ def a_function(arg1: str, arg2: int) -> tuple[float, int]:
""" """
``` ```
The linter rules we use for docstrings are defined by [pydocstyle](https://docs.astral.sh/ruff/rules/#pydocstyle-d). We do not use rules D203, D213, D400. +The linter rules we use for docstrings are defined by [pydocstyle](https://docs.astral.sh/ruff/rules/#pydocstyle-d). We do not use rules D203, D213, D400 for reasons explained in our `pyproject.toml` file.
The documentation generated by pydoctor from docstrings can be viewed in any merge request (if the CI pipeline has passed) using the "View App" button. The documentation generated by pydoctor from docstrings can be viewed in any merge request (if the CI pipeline has passed) using the "View App" button.