From 4bdb210ead89c239db19559d7b8e5038a8eda34c Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Fri, 19 Jun 2026 16:45:14 +0100 Subject: [PATCH 01/15] Get CodeCov badge working --- .github/workflows/test.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 683408fc..0fea01d9 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -168,6 +168,13 @@ jobs: send-summary-comment: true show-annotations: "warning" + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v4 + with: + token: ${{ secrets.CODECOV_TOKEN }} + files: ./coverage.lcov + fail_ci_if_error: false + test-against-ofm-v3: runs-on: ubuntu-latest defaults: From 29a3e01ff0d405bc304b043b903f6e94d9dfd1d6 Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Fri, 19 Jun 2026 17:00:31 +0100 Subject: [PATCH 02/15] Try updating badge for coverage to another tool --- .github/workflows/test.yml | 31 ++++++++++++++++++++++--------- README.md | 2 +- 2 files changed, 23 insertions(+), 10 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 0fea01d9..76b015ad 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -77,13 +77,15 @@ jobs: run: flake8 src - name: Test with pytest - run: pytest --cov=src --cov-report=lcov + run: pytest --cov=src --cov-report=lcov --cov-report=json - name: Upload code coverage uses: actions/upload-artifact@v4 with: name: coverage-${{ matrix.python }} - path: ./coverage.lcov + path: | + ./coverage.lcov + ./coverage.json - name: Analyse with MyPy run: mypy @@ -136,6 +138,24 @@ jobs: with: name: coverage-3.12 + - name: Parse coverage percentage + id: get-coverage + run: | + COVERAGE=$(jq -r '.totals.percent_covered_display' coverage.json) + echo "coverage=$COVERAGE" >> $GITHUB_OUTPUT + + - name: Update Coverage Badge + # Only run this on the main branch so PRs don't overwrite the main badge + if: github.ref == 'refs/heads/main' + uses: Schneegans/dynamic-badges-action@v1.7.0 + with: + auth: ${{ secrets.GIST_SECRET }} + gistID: 936bcec8e1815a49d1e7f947924ffa3f + filename: labthings-fastapi-coverage.json + label: coverage + message: ${{ steps.get-coverage.outputs.coverage }}% + color: green + - name: Download code coverage report for base branch id: download-base-coverage continue-on-error: true @@ -168,13 +188,6 @@ jobs: send-summary-comment: true show-annotations: "warning" - - name: Upload coverage to Codecov - uses: codecov/codecov-action@v4 - with: - token: ${{ secrets.CODECOV_TOKEN }} - files: ./coverage.lcov - fail_ci_if_error: false - test-against-ofm-v3: runs-on: ubuntu-latest defaults: diff --git a/README.md b/README.md index 9395a8ec..c73cd985 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![codecov](https://codecov.io/gh/rwb27/labthings-fastapi/branch/main/graph/badge.svg?token=IR4QNA8X6M)](https://codecov.io/gh/rwb27/labthings-fastapi) +![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/bprobert97/936bcec8e1815a49d1e7f947924ffa3f/raw/labthings-fastapi-coverage.json) [![Documentation Status](https://readthedocs.org/projects/labthings-fastapi/badge/?version=latest)](https://labthings-fastapi.readthedocs.io/en/latest/?badge=latest) # labthings-fastapi From d267abb83ea49c5798f1d44d5f565b7c1124f44c Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Fri, 19 Jun 2026 17:04:54 +0100 Subject: [PATCH 03/15] Delete main branch check --- .github/workflows/test.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 76b015ad..40fe33ba 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -145,8 +145,6 @@ jobs: echo "coverage=$COVERAGE" >> $GITHUB_OUTPUT - name: Update Coverage Badge - # Only run this on the main branch so PRs don't overwrite the main badge - if: github.ref == 'refs/heads/main' uses: Schneegans/dynamic-badges-action@v1.7.0 with: auth: ${{ secrets.GIST_SECRET }} From c863073726567bdf8f14fc65d35d40792f469ea5 Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Fri, 19 Jun 2026 17:10:10 +0100 Subject: [PATCH 04/15] Add back in main branch check --- .github/workflows/test.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 40fe33ba..76b015ad 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -145,6 +145,8 @@ jobs: echo "coverage=$COVERAGE" >> $GITHUB_OUTPUT - name: Update Coverage Badge + # Only run this on the main branch so PRs don't overwrite the main badge + if: github.ref == 'refs/heads/main' uses: Schneegans/dynamic-badges-action@v1.7.0 with: auth: ${{ secrets.GIST_SECRET }} From 7ba5ae91240dd5319ded7d8477044fc242c5f4f4 Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Fri, 19 Jun 2026 17:38:24 +0100 Subject: [PATCH 05/15] Add testing.md file --- docs/source/testing.md | 85 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 docs/source/testing.md diff --git a/docs/source/testing.md b/docs/source/testing.md new file mode 100644 index 00000000..47945290 --- /dev/null +++ b/docs/source/testing.md @@ -0,0 +1,85 @@ +# Testing `labthings-fastapi` + +Our test suite ensures the framework functions correctly, maintains code quality, and integrates seamlessly with static type checkers. + +## Continuous Integration (CI) Pipeline + +When you submit a Pull Request (PR), our GitHub Actions CI pipeline automatically runs a comprehensive suite of checks. Your PR must pass these checks before it can be merged. + +Here is what the CI pipeline tests: + +* **Matrix Testing:** We run the core test suite (`pytest`) and static type checks (`mypy`) across Python versions 3.10, 3.11, 3.12, and 3.13. +* **Code Quality & Security:** The pipeline runs `ruff` (formatting and linting), `flake8` (docstrings), `codespell` (spelling), and a `pip-audit` to check for dependency vulnerabilities. +* **Coverage:** We track code coverage. A report is generated on your PR to show if your changes increased or decreased overall test coverage. +* **Dependency Checks:** We run the tests twice: once with pinned dependencies (`dev-requirements.txt`) for reproducibility, and once with unpinned dependencies (`.[dev]`) to catch upstream breakages early. +* **Downstream Integration:** The pipeline installs your version of `labthings-fastapi` alongside the `v3` branch of the OpenFlexure Microscope Server. It then runs the entire OFM test suite (unit, integration, and lifecycle) to guarantee backwards compatibility. *(Note: You can target a specific OFM branch by adding `OFM-Feature-Branch: branch-name` to your PR description).* + +--- + +## Running Core Tests Locally + +To ensure your code will pass CI, you should run these checks locally before pushing your commits. + +### 1. Local Environment Setup + +We recommend running the test suite using the pinned development dependencies to mirror the primary CI environment. Ensure you have cloned the repository, then install the package and dependencies: + +```bash +git clone https://github.com/labthings/labthings-fastapi.git +cd labthings-fastapi +pip install -e . -r dev-requirements.txt +``` + +### 2. Linting, Formatting, and Spelling + +Check that your code adheres to the project's formatting and style guidelines from the root of the repository: + +* **Linting:** `ruff check .` +* **Formatting:** `ruff format --check .` +* **Spelling:** `codespell .` +* **Docstrings:** `flake8 src` + +### 3. Static Type Checking + +`labthings-fastapi` is designed to be fully type-hinted. We explicitly test that `mypy` can infer the correct types for `Thing` attributes. Run static type checking across the source code and our dedicated typing tests folder: + +```bash +mypy src typing_tests +``` + +### 4. Unit Tests & Coverage + +We use `pytest` for our core test suite. Execute the unit tests and generate a coverage report using: + +```bash +pytest --cov=src +``` + +--- + +## Downstream Integration Testing Locally + +Because `labthings-fastapi` underpins the [OpenFlexure Microscope software], major architectural changes should be tested against the downstream server locally. This matches the `test-against-ofm-v3` job in our CI pipeline. + +Assuming you have both repositories cloned in the same parent directory: + +```bash +# 1. Setup the OpenFlexure Microscope Server +cd ../openflexure-microscope-server +git checkout v3 +pip install -e .[dev] + +# 2. Install your local version of labthings-fastapi +pip install -e ../labthings-fastapi + +# 3. Pull the OFM web app (required for integration) +python ./pull_webapp.py + +# 4. Run the OFM Test Suite +pytest # Run OFM unit tests +pytest tests/integration_tests # Run OFM integration tests +python tests/lifecycle_test/testfile.py # Run OFM lifecycle tests +mypy src # Run OFM static type checks +``` + +[OpenFlexure Microscope software]: https://gitlab.com/openflexure/openflexure-microscope-server/ \ No newline at end of file From e8b42f777128e7c0d49c03a416d07a1ac37ff07f Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Mon, 29 Jun 2026 16:12:24 +0100 Subject: [PATCH 06/15] De-duplictae pytest commands --- .github/workflows/test.yml | 6 +++--- pyproject.toml | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 76b015ad..4e18cb5c 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -22,7 +22,7 @@ jobs: - name: Test with pytest run: | - pytest --cov=src --cov-report=lcov + pytest mv coverage.lcov base-coverage.lcov - name: Upload code coverage for base branch @@ -77,7 +77,7 @@ jobs: run: flake8 src - name: Test with pytest - run: pytest --cov=src --cov-report=lcov --cov-report=json + run: pytest - name: Upload code coverage uses: actions/upload-artifact@v4 @@ -123,7 +123,7 @@ jobs: - name: Test with pytest if: success() || failure() - run: pytest --cov=src --cov-report=lcov + run: pytest - name: Check quickstart, including installation if: success() || failure() diff --git a/pyproject.toml b/pyproject.toml index 155a0425..2122c139 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -70,6 +70,8 @@ addopts = [ "--cov-report=xml:coverage.xml", "--cov-report=html:htmlcov", "--cov-report=lcov", + "--cov=src", + "--cov-report=json", ] markers = [ "slow: marks tests as slow (deselect with '-m \"not slow\"')", From 668b5b2363492fa7c51c525dc3b3bc65d158f9be Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Mon, 29 Jun 2026 16:13:27 +0100 Subject: [PATCH 07/15] Remove args not needed in examples --- docs/source/testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/testing.md b/docs/source/testing.md index 47945290..5f3a8428 100644 --- a/docs/source/testing.md +++ b/docs/source/testing.md @@ -44,7 +44,7 @@ Check that your code adheres to the project's formatting and style guidelines fr `labthings-fastapi` is designed to be fully type-hinted. We explicitly test that `mypy` can infer the correct types for `Thing` attributes. Run static type checking across the source code and our dedicated typing tests folder: ```bash -mypy src typing_tests +mypy ``` ### 4. Unit Tests & Coverage @@ -52,7 +52,7 @@ mypy src typing_tests We use `pytest` for our core test suite. Execute the unit tests and generate a coverage report using: ```bash -pytest --cov=src +pytest ``` --- From e8b0c168d2b17b1761f216e913fb1c696260d2f5 Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Mon, 29 Jun 2026 16:17:45 +0100 Subject: [PATCH 08/15] Dynamic colour of badge --- .github/workflows/test.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 4e18cb5c..d962fefe 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -154,7 +154,9 @@ jobs: filename: labthings-fastapi-coverage.json label: coverage message: ${{ steps.get-coverage.outputs.coverage }}% - color: green + valColorRange: ${{ steps.get-coverage.outputs.coverage }} + maxColorRange: 90 + minColorRange: 50 - name: Download code coverage report for base branch id: download-base-coverage From 70b25d29749228771b0afc2e4e5ec9f1c9272a74 Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Mon, 29 Jun 2026 16:22:51 +0100 Subject: [PATCH 09/15] Update pip install command --- docs/source/testing.md | 2 +- docs/source/tutorial/installing_labthings.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/testing.md b/docs/source/testing.md index 5f3a8428..8528d640 100644 --- a/docs/source/testing.md +++ b/docs/source/testing.md @@ -67,7 +67,7 @@ Assuming you have both repositories cloned in the same parent directory: # 1. Setup the OpenFlexure Microscope Server cd ../openflexure-microscope-server git checkout v3 -pip install -e .[dev] +pip install -r dev-requirements.txt # 2. Install your local version of labthings-fastapi pip install -e ../labthings-fastapi diff --git a/docs/source/tutorial/installing_labthings.rst b/docs/source/tutorial/installing_labthings.rst index fc82302f..64ad10c7 100644 --- a/docs/source/tutorial/installing_labthings.rst +++ b/docs/source/tutorial/installing_labthings.rst @@ -23,6 +23,6 @@ then install labthings with: :start-after: BEGIN install :end-before: END install -It is also possible to install LabThings from source, by cloning the GitHub repository and running ``pip install -e .[dev]``, but this is only recommended if you intend to alter the LabThings-FastAPI library; it is best to use the published package unless you have a good reason not to. +It is also possible to install LabThings from source, by cloning the GitHub repository and running ``pip install -r dev-requirements.txt``, but this is only recommended if you intend to alter the LabThings-FastAPI library; it is best to use the published package unless you have a good reason not to. .. _PyPI: https://pypi.org/project/labthings-fastapi/ \ No newline at end of file From d4aa1122e4842782e4fabcc039ef67c6a356239b Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Mon, 29 Jun 2026 16:48:59 +0100 Subject: [PATCH 10/15] And links between testing and contributing docs --- CONTRIBUTING.md | 5 ++++- README.md | 3 ++- docs/source/index.rst | 1 + docs/source/labthings-testing.md | 1 + docs/source/testing.md | 10 +++++++++- 5 files changed, 17 insertions(+), 3 deletions(-) create mode 100644 docs/source/labthings-testing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5784c876..7d205fc0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,6 +45,8 @@ pip install -r dev-requirements.txt We use several tools to maintain code quality. All of these run in CI with [GitHub Actions], but you should run them locally before submitting a Pull Request. Both `ruff` and `flake8` are configured from [`pyproject.toml`]. +More detailed information on our testing and linting can be found in [`testing.md`] + * **Linting:** We use [`ruff`] for fast linting and formatting. We highly recommend setting up a pre-commit hook to ensure [`ruff`] passes on every commit. ```bash ruff format --check @@ -119,4 +121,5 @@ All changes to the codebase must go via pull requests. Unless you are a core mai [`flake8`]: https://flake8.pycqa.org/en/latest/ [`mypy`]: https://mypy-lang.org/ [`pytest`]: https://docs.pytest.org/en/stable/ -[`uv`]: https://docs.astral.sh/uv/ \ No newline at end of file +[`uv`]: https://docs.astral.sh/uv/ +[`testing.md`]: ./docs/source/testing.md \ No newline at end of file diff --git a/README.md b/README.md index 90ee3ec1..806607c6 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ See [readthedocs] for installation instructions that are automatically tested. Y > > *If you are using a centrally managed machine, you will need administrator privileges to install these system-level dependencies.* -For instructions on how to set up a development environment, run tests, and contribute to this project, please see [CONTRIBUTING.md]. +For instructions on how to set up a development environment, run tests, and contribute to this project, please see [CONTRIBUTING.md] and [`testing.md`]. ## Demo @@ -34,3 +34,4 @@ See [readthedocs] for a runnable demo. [pre-commit hook]: https://openflexure.org/contribute#use-git-hooks-for-ci-checks [readthedocs]: https://labthings-fastapi.readthedocs.io/ [CONTRIBUTING.md]: ./CONTRIBUTING.md +[`testing.md`]: ./docs/source/testing.md diff --git a/docs/source/index.rst b/docs/source/index.rst index 6ddf88a6..85b4fc87 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -19,6 +19,7 @@ Documentation for LabThings-FastAPI updates_and_features.rst see_also.rst examples.rst + labthings_testing.md wot_core_concepts.rst removed_features.rst diff --git a/docs/source/labthings-testing.md b/docs/source/labthings-testing.md new file mode 100644 index 00000000..52d4a6a7 --- /dev/null +++ b/docs/source/labthings-testing.md @@ -0,0 +1 @@ +```{include} testing.md \ No newline at end of file diff --git a/docs/source/testing.md b/docs/source/testing.md index 8528d640..ebb3d703 100644 --- a/docs/source/testing.md +++ b/docs/source/testing.md @@ -5,6 +5,7 @@ Our test suite ensures the framework functions correctly, maintains code quality ## Continuous Integration (CI) Pipeline When you submit a Pull Request (PR), our GitHub Actions CI pipeline automatically runs a comprehensive suite of checks. Your PR must pass these checks before it can be merged. +You can find out more about contributing code in [`CONTRIBUTING.md`]. Here is what the CI pipeline tests: @@ -30,6 +31,12 @@ cd labthings-fastapi pip install -e . -r dev-requirements.txt ``` +> **Note: Windows Installations on devices with ARM processors** +> +> Installing on Windows devices with ARM processors requires Visual Studio with the **"Desktop development with C++"** workload enabled. This is necessary because `pydantic` relies on Rust, which in turn requires C++ build tools to compile. +> +> *If you are using a centrally managed machine, you will need administrator privileges to install these system-level dependencies.* + ### 2. Linting, Formatting, and Spelling Check that your code adheres to the project's formatting and style guidelines from the root of the repository: @@ -82,4 +89,5 @@ python tests/lifecycle_test/testfile.py # Run OFM lifecycle tests mypy src # Run OFM static type checks ``` -[OpenFlexure Microscope software]: https://gitlab.com/openflexure/openflexure-microscope-server/ \ No newline at end of file +[OpenFlexure Microscope software]: https://gitlab.com/openflexure/openflexure-microscope-server/ +[`CONTRIBUTING.md`]: ../../CONTRIBUTING.md \ No newline at end of file From 45dde2a41e8e773c78b2c24d816598952c9b507a Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Mon, 29 Jun 2026 16:55:46 +0100 Subject: [PATCH 11/15] Fix typos --- CONTRIBUTING.md | 2 +- docs/source/labthings-testing.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d205fc0..cfbb58f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,7 +45,7 @@ pip install -r dev-requirements.txt We use several tools to maintain code quality. All of these run in CI with [GitHub Actions], but you should run them locally before submitting a Pull Request. Both `ruff` and `flake8` are configured from [`pyproject.toml`]. -More detailed information on our testing and linting can be found in [`testing.md`] +More detailed information on our testing and linting can be found in [`testing.md`]. * **Linting:** We use [`ruff`] for fast linting and formatting. We highly recommend setting up a pre-commit hook to ensure [`ruff`] passes on every commit. ```bash diff --git a/docs/source/labthings-testing.md b/docs/source/labthings-testing.md index 52d4a6a7..e96daf08 100644 --- a/docs/source/labthings-testing.md +++ b/docs/source/labthings-testing.md @@ -1 +1 @@ -```{include} testing.md \ No newline at end of file +```{include} ./testing.md \ No newline at end of file From 54bd881d5d1c26009966c840e2e95cb7a62a54cf Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Mon, 29 Jun 2026 16:58:52 +0100 Subject: [PATCH 12/15] Fix name typo --- docs/source/{labthings-testing.md => labthings_testing.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/source/{labthings-testing.md => labthings_testing.md} (100%) diff --git a/docs/source/labthings-testing.md b/docs/source/labthings_testing.md similarity index 100% rename from docs/source/labthings-testing.md rename to docs/source/labthings_testing.md From a5cb4f0255dbd51e4245c2abf2aea0dc621ddda3 Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Mon, 29 Jun 2026 17:00:47 +0100 Subject: [PATCH 13/15] Improve title formatting --- docs/source/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/testing.md b/docs/source/testing.md index ebb3d703..c280c42a 100644 --- a/docs/source/testing.md +++ b/docs/source/testing.md @@ -1,4 +1,4 @@ -# Testing `labthings-fastapi` +# Testing labthings-fastapi Our test suite ensures the framework functions correctly, maintains code quality, and integrates seamlessly with static type checkers. From 733ca2655a5de4ceeb8558787e9d95b51360cecc Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Tue, 30 Jun 2026 10:28:41 +0100 Subject: [PATCH 14/15] Aim to fix links using stubs --- CONTRIBUTING.md | 124 +----------------------------- README.md | 2 +- docs/source/contributing.md | 126 ++++++++++++++++++++++++++++++- docs/source/index.rst | 2 +- docs/source/labthings_testing.md | 1 - docs/source/testing.md | 2 +- 6 files changed, 130 insertions(+), 127 deletions(-) delete mode 100644 docs/source/labthings_testing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cfbb58f4..a5e6f03e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,125 +1,5 @@ # Contributing to labthings-fastapi -First off, thank you for considering contributing to `labthings-fastapi`! We welcome contributions from everyone, whether it's reporting a bug, suggesting a feature, improving documentation, or writing code. +Thank you for your interest in contributing! -This document outlines the processes for getting help, reporting issues, and contributing to the codebase. - -## Seeking Support - -If you have a question about how to use `labthings-fastapi`, or if you are running into trouble: - -* **Check the Documentation:** Please review the official documentation on [readthedocs]. -* **GitHub Discussions / Issues:** If you cannot find the answer, feel free to open an issue on our [GitHub Issues page]. -* **OpenFlexure Community:** Because `labthings-fastapi` is the underlying framework for v3 of the [OpenFlexure Microscope software], you may also find support by engaging with the broader [OpenFlexure Forum]. - -## Reporting Issues or Bugs - -If you find a bug or have a feature request, please report it by opening an issue on our [GitHub Issues page]. - -When reporting an issue, please include as much detail as possible: - -* **Description:** A clear and concise description of what the bug is. -* **Reproduction steps:** How can we reproduce the problem? (A minimal reproducible example is highly appreciated). -* **Expected behaviour:** What did you expect to happen? -* **Environment:** Include your OS, Python version, and `labthings-fastapi` version. Include full error tracebacks if applicable. - -## Contributing Code or Documentation - -We welcome pull requests for bug fixes, new features, and documentation improvements. - -### 1. Local Development Setup - -To work on the code, you will need to clone the repository and install the development dependencies. -Please see the [installation notes](./README.md#installation-notes) for more detail about compatible Python versions and Windows installation. - -```bash -# Clone the repository -git clone https://github.com/labthings/labthings-fastapi.git -cd labthings-fastapi - -# Install the package in editable mode with development dependencies -pip install -r dev-requirements.txt -``` - -### 2. Linting and Testing - -We use several tools to maintain code quality. All of these run in CI with [GitHub Actions], but you should run them locally before submitting a Pull Request. Both `ruff` and `flake8` are configured from [`pyproject.toml`]. - -More detailed information on our testing and linting can be found in [`testing.md`]. - -* **Linting:** We use [`ruff`] for fast linting and formatting. We highly recommend setting up a pre-commit hook to ensure [`ruff`] passes on every commit. - ```bash - ruff format --check - ruff check . - ``` - -* **Docstrings:** [`flake8`] is primarily used to enable stricter checks on docstrings. - ```bash - flake8 src - ``` - -* **Spelling:** We use [`codespell`] to prevent common spelling mistakes in code and documentation. - ```bash - codespell . - ``` - -* **Type Checking:** We use [`mypy`] for static type checking. It is configured in `pyproject.toml`. - ```bash - mypy - ``` - -* **Testing:** We use [`pytest`] for our test suite and test coverage. Ensure all tests pass locally. - ```bash - pytest --cov=src - ``` - -### 3. Managing Dependencies - -Dependencies are defined in [`pyproject.toml`]. If you need to compile a `dev-requirements.txt` file (e.g., for reproducible CI/CD or local isolated environments), you can do so using [`uv`]: - -```bash -uv pip compile --extra dev pyproject.toml --output-file dev-requirements.txt -``` - -*(If you're not using `uv`, regular `pip-compile` from `pip-tools` will achieve the same thing).* - -### 4. Submitting a Pull Request (PR) - -All changes to the codebase must go via pull requests. Unless you are a core maintainer with write access, please use the standard fork-and-branch workflow: - -1. **Fork the repository** to your own GitHub account using the "Fork" button at the top of the repository page. -2. **Clone your fork** locally and set up the upstream remote: - ```bash - git clone https://github.com/YOUR-USERNAME/labthings-fastapi.git - cd labthings-fastapi - git remote add upstream https://github.com/labthings/labthings-fastapi.git - ``` -3. **Create a new branch** for your feature or bugfix: - ```bash - git checkout -b feature-name - ``` -4. **Commit your changes** with clear, descriptive commit messages. -5. **Push your branch** up to your fork: - ```bash - git push origin feature-name - ``` -6. **Open a Pull Request** against the `main` branch of the `labthings/labthings-fastapi` repository. - -**Pull Request Guidelines:** - -* Code should only be merged once all the checks in the CI test job are passing. -* **Unpinned Dependencies:** Note that we have a specific CI job called `test-with-unpinned-dependencies`. It is acceptable to merge code if only this specific job fails, provided the failure is due to upstream dependency issues. We prefer to deal with upstream dependency issues in a separate PR, particularly when the required fixes are distinct from the code in your current PR. The same applies to the `pip-audit` job. -* Update documentation (`docs/` or docstrings) if your changes modify existing behavior or add new features. - -[readthedocs]: https://labthings-fastapi.readthedocs.io/ -[GitHub Issues page]: https://github.com/labthings/labthings-fastapi/issues -[OpenFlexure Forum]: https://openflexure.discourse.group/ -[OpenFlexure Microscope software]: https://gitlab.com/openflexure/openflexure-microscope-server/ -[GitHub Actions]: https://github.com/labthings/labthings-fastapi/actions -[`ruff`]: https://docs.astral.sh/ruff/ -[`pyproject.toml`]: ./pyproject.toml -[`flake8`]: https://flake8.pycqa.org/en/latest/ -[`mypy`]: https://mypy-lang.org/ -[`pytest`]: https://docs.pytest.org/en/stable/ -[`uv`]: https://docs.astral.sh/uv/ -[`testing.md`]: ./docs/source/testing.md \ No newline at end of file +Please read our full [Contributor Guidelines](./docs/source/contributing.md). diff --git a/README.md b/README.md index 806607c6..f3287f9e 100644 --- a/README.md +++ b/README.md @@ -33,5 +33,5 @@ See [readthedocs] for a runnable demo. [OpenFlexure Microscope software]: https://gitlab.com/openflexure/openflexure-microscope-server/ [pre-commit hook]: https://openflexure.org/contribute#use-git-hooks-for-ci-checks [readthedocs]: https://labthings-fastapi.readthedocs.io/ -[CONTRIBUTING.md]: ./CONTRIBUTING.md +[CONTRIBUTING.md]: ./docs/source/contributing.md [`testing.md`]: ./docs/source/testing.md diff --git a/docs/source/contributing.md b/docs/source/contributing.md index b2d2646a..8b7a3e41 100644 --- a/docs/source/contributing.md +++ b/docs/source/contributing.md @@ -1 +1,125 @@ -```{include} ../../CONTRIBUTING.md +# Contributing to labthings-fastapi + +First off, thank you for considering contributing to `labthings-fastapi`! We welcome contributions from everyone, whether it's reporting a bug, suggesting a feature, improving documentation, or writing code. + +This document outlines the processes for getting help, reporting issues, and contributing to the codebase. + +## Seeking Support + +If you have a question about how to use `labthings-fastapi`, or if you are running into trouble: + +* **Check the Documentation:** Please review the official documentation on [readthedocs]. +* **GitHub Discussions / Issues:** If you cannot find the answer, feel free to open an issue on our [GitHub Issues page]. +* **OpenFlexure Community:** Because `labthings-fastapi` is the underlying framework for v3 of the [OpenFlexure Microscope software], you may also find support by engaging with the broader [OpenFlexure Forum]. + +## Reporting Issues or Bugs + +If you find a bug or have a feature request, please report it by opening an issue on our [GitHub Issues page]. + +When reporting an issue, please include as much detail as possible: + +* **Description:** A clear and concise description of what the bug is. +* **Reproduction steps:** How can we reproduce the problem? (A minimal reproducible example is highly appreciated). +* **Expected behaviour:** What did you expect to happen? +* **Environment:** Include your OS, Python version, and `labthings-fastapi` version. Include full error tracebacks if applicable. + +## Contributing Code or Documentation + +We welcome pull requests for bug fixes, new features, and documentation improvements. + +### 1. Local Development Setup + +To work on the code, you will need to clone the repository and install the development dependencies. +Please see the [installation notes](./README.md#installation-notes) for more detail about compatible Python versions and Windows installation. + +```bash +# Clone the repository +git clone https://github.com/labthings/labthings-fastapi.git +cd labthings-fastapi + +# Install the package in editable mode with development dependencies +pip install -r dev-requirements.txt +``` + +### 2. Linting and Testing + +We use several tools to maintain code quality. All of these run in CI with [GitHub Actions], but you should run them locally before submitting a Pull Request. Both `ruff` and `flake8` are configured from [`pyproject.toml`]. + +More detailed information on our testing and linting can be found in [`testing.md`]. + +* **Linting:** We use [`ruff`] for fast linting and formatting. We highly recommend setting up a pre-commit hook to ensure [`ruff`] passes on every commit. + ```bash + ruff format --check + ruff check . + ``` + +* **Docstrings:** [`flake8`] is primarily used to enable stricter checks on docstrings. + ```bash + flake8 src + ``` + +* **Spelling:** We use [`codespell`] to prevent common spelling mistakes in code and documentation. + ```bash + codespell . + ``` + +* **Type Checking:** We use [`mypy`] for static type checking. It is configured in `pyproject.toml`. + ```bash + mypy + ``` + +* **Testing:** We use [`pytest`] for our test suite and test coverage. Ensure all tests pass locally. + ```bash + pytest --cov=src + ``` + +### 3. Managing Dependencies + +Dependencies are defined in [`pyproject.toml`]. If you need to compile a `dev-requirements.txt` file (e.g., for reproducible CI/CD or local isolated environments), you can do so using [`uv`]: + +```bash +uv pip compile --extra dev pyproject.toml --output-file dev-requirements.txt +``` + +*(If you're not using `uv`, regular `pip-compile` from `pip-tools` will achieve the same thing).* + +### 4. Submitting a Pull Request (PR) + +All changes to the codebase must go via pull requests. Unless you are a core maintainer with write access, please use the standard fork-and-branch workflow: + +1. **Fork the repository** to your own GitHub account using the "Fork" button at the top of the repository page. +2. **Clone your fork** locally and set up the upstream remote: + ```bash + git clone https://github.com/YOUR-USERNAME/labthings-fastapi.git + cd labthings-fastapi + git remote add upstream https://github.com/labthings/labthings-fastapi.git + ``` +3. **Create a new branch** for your feature or bugfix: + ```bash + git checkout -b feature-name + ``` +4. **Commit your changes** with clear, descriptive commit messages. +5. **Push your branch** up to your fork: + ```bash + git push origin feature-name + ``` +6. **Open a Pull Request** against the `main` branch of the `labthings/labthings-fastapi` repository. + +**Pull Request Guidelines:** + +* Code should only be merged once all the checks in the CI test job are passing. +* **Unpinned Dependencies:** Note that we have a specific CI job called `test-with-unpinned-dependencies`. It is acceptable to merge code if only this specific job fails, provided the failure is due to upstream dependency issues. We prefer to deal with upstream dependency issues in a separate PR, particularly when the required fixes are distinct from the code in your current PR. The same applies to the `pip-audit` job. +* Update documentation (`docs/` or docstrings) if your changes modify existing behavior or add new features. + +[readthedocs]: https://labthings-fastapi.readthedocs.io/ +[GitHub Issues page]: https://github.com/labthings/labthings-fastapi/issues +[OpenFlexure Forum]: https://openflexure.discourse.group/ +[OpenFlexure Microscope software]: https://gitlab.com/openflexure/openflexure-microscope-server/ +[GitHub Actions]: https://github.com/labthings/labthings-fastapi/actions +[`ruff`]: https://docs.astral.sh/ruff/ +[`pyproject.toml`]: ./pyproject.toml +[`flake8`]: https://flake8.pycqa.org/en/latest/ +[`mypy`]: https://mypy-lang.org/ +[`pytest`]: https://docs.pytest.org/en/stable/ +[`uv`]: https://docs.astral.sh/uv/ +[`testing.md`]: ./testing.md \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 85b4fc87..a4829189 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -19,7 +19,7 @@ Documentation for LabThings-FastAPI updates_and_features.rst see_also.rst examples.rst - labthings_testing.md + testing.md wot_core_concepts.rst removed_features.rst diff --git a/docs/source/labthings_testing.md b/docs/source/labthings_testing.md deleted file mode 100644 index e96daf08..00000000 --- a/docs/source/labthings_testing.md +++ /dev/null @@ -1 +0,0 @@ -```{include} ./testing.md \ No newline at end of file diff --git a/docs/source/testing.md b/docs/source/testing.md index c280c42a..f474a7d5 100644 --- a/docs/source/testing.md +++ b/docs/source/testing.md @@ -90,4 +90,4 @@ mypy src # Run OFM static type checks ``` [OpenFlexure Microscope software]: https://gitlab.com/openflexure/openflexure-microscope-server/ -[`CONTRIBUTING.md`]: ../../CONTRIBUTING.md \ No newline at end of file +[`CONTRIBUTING.md`]: ./contributing.md \ No newline at end of file From 13edece5261cf6885fea3ac96be4e9c29126b9da Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Tue, 30 Jun 2026 10:33:33 +0100 Subject: [PATCH 15/15] Change refernece names to be guidelines not md files --- README.md | 6 +++--- docs/source/contributing.md | 4 ++-- docs/source/testing.md | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f3287f9e..e4c59e49 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ See [readthedocs] for installation instructions that are automatically tested. Y > > *If you are using a centrally managed machine, you will need administrator privileges to install these system-level dependencies.* -For instructions on how to set up a development environment, run tests, and contribute to this project, please see [CONTRIBUTING.md] and [`testing.md`]. +For instructions on how to set up a development environment, run tests, and contribute to this project, please see our [Contributor Guidelines] and [Testing Guidelines]. ## Demo @@ -33,5 +33,5 @@ See [readthedocs] for a runnable demo. [OpenFlexure Microscope software]: https://gitlab.com/openflexure/openflexure-microscope-server/ [pre-commit hook]: https://openflexure.org/contribute#use-git-hooks-for-ci-checks [readthedocs]: https://labthings-fastapi.readthedocs.io/ -[CONTRIBUTING.md]: ./docs/source/contributing.md -[`testing.md`]: ./docs/source/testing.md +[Contributor Guidelines]: ./docs/source/contributing.md +[Testing Guidelines]: ./docs/source/testing.md diff --git a/docs/source/contributing.md b/docs/source/contributing.md index 8b7a3e41..468de7c7 100644 --- a/docs/source/contributing.md +++ b/docs/source/contributing.md @@ -45,7 +45,7 @@ pip install -r dev-requirements.txt We use several tools to maintain code quality. All of these run in CI with [GitHub Actions], but you should run them locally before submitting a Pull Request. Both `ruff` and `flake8` are configured from [`pyproject.toml`]. -More detailed information on our testing and linting can be found in [`testing.md`]. +More detailed information on our testing and linting can be found in our [Testing Guidelines]. * **Linting:** We use [`ruff`] for fast linting and formatting. We highly recommend setting up a pre-commit hook to ensure [`ruff`] passes on every commit. ```bash @@ -122,4 +122,4 @@ All changes to the codebase must go via pull requests. Unless you are a core mai [`mypy`]: https://mypy-lang.org/ [`pytest`]: https://docs.pytest.org/en/stable/ [`uv`]: https://docs.astral.sh/uv/ -[`testing.md`]: ./testing.md \ No newline at end of file +[Testing Guidelines]: ./testing.md \ No newline at end of file diff --git a/docs/source/testing.md b/docs/source/testing.md index f474a7d5..d929edf4 100644 --- a/docs/source/testing.md +++ b/docs/source/testing.md @@ -5,7 +5,7 @@ Our test suite ensures the framework functions correctly, maintains code quality ## Continuous Integration (CI) Pipeline When you submit a Pull Request (PR), our GitHub Actions CI pipeline automatically runs a comprehensive suite of checks. Your PR must pass these checks before it can be merged. -You can find out more about contributing code in [`CONTRIBUTING.md`]. +You can find out more about contributing code in our [Contributor Guidelines]. Here is what the CI pipeline tests: @@ -90,4 +90,4 @@ mypy src # Run OFM static type checks ``` [OpenFlexure Microscope software]: https://gitlab.com/openflexure/openflexure-microscope-server/ -[`CONTRIBUTING.md`]: ./contributing.md \ No newline at end of file +[Contributor Guidelines]: ./contributing.md \ No newline at end of file