[DOCS] restructure and improve contributing guide

Author: sophiamaedler

docs/CONTRIBUTING.md

@@ -2,94 +2,126 @@
 
 Contributions to scPortrait are welcome! This section provides some guidelines and tips to follow when contributing.
 
-## Installing dev dependencies
+## Creating a development Environment and installing dev dependencies
 
-In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build the documentation_. It's easy to install them using `pip`:
+It's recommended to do development work in an isolated environment.
+There are number of ways to do this, including virtual environments, conda environments, and virtual machines.
+
+We use conda environments. To setup a conda environment please do the following:
 
-```bash
+```console
+conda create -n "{dev_environment_name}" python=3.12
+conda activate {dev_environment_name}
+```
+
+In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build the documentation_. It's easy to install them using `pip` by adding the `dev` tag:
+
+### Interactive Installation
+```console
 git clone https://github.com/MannLabs/scPortrait
 cd scPortrait
 pip install -e '.[dev]'
 ```
 
-## Code-style
+### Installation from PyPi
+```console
+pip install scportrait[dev]
+```
 
-This project uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either automatically fix issues with the code, or raise an error message.
+## Committing Code Changes
 
-To enable pre-commit locally, simply run
+We assume some familiarity with `git`. For more detailed information, we recommend the following introductions:
 
-```console
-pre-commit install
-```
+- [Atlassian's git tutorial][] — beginner-friendly introduction to the git command line
+- [Setting up git for GitHub][] — configuring git to work with your GitHub account
 
-in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time.
+In short, contributing changes to scPortrait follows this workflow:
 
-Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. If you didn't run `pre-commit` before pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message.
+1. **Fork and clone the repository**
+   See: [Forking and cloning](#forking-and-cloning)
 
-If pre-commit.ci added a commit on a branch you still have been working on locally, simply use
+2. **Set up pre-commit hooks**
+   Ensures consistent formatting and linting across contributions.
+   See: [Setting up `pre-commit`](#setting-up-pre-commit)
 
-```console
-git pull --rebase
-```
-to integrate the changes into yours.
+3. **Create a new branch for your changes**
+   Development should occur on a separate branch.
+   See: [Creating a branch for your feature](#creating-a-branch-for-your-feature)
 
-While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage.
+4. **Commit your changes with clear commit messages**
+   See: [Commit Message Guidelines](#commit-message-guidelines)
 
-## Writing documentation
+5. **Open a pull request**
+   Submit your branch to the `main` branch of the main repository.
+   See: [Open a pull request](#open-a-pull-request)
 
-Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features:
+We encourage small, focused pull requests, as these are easier to review and discuss.
 
--   Google-style docstrings, where the __init__ method should be documented in its own docstring, not at the class level.
--   there should be no specification of type in the docstrings (this should be done in the function call with mypy style type hints instead)
--   add type hints for use with mypy
--   example code
--   automatic building with Sphinx
+### Forking and cloning
 
-Refer to [sphinx google style docstrings][] for detailed information on writing documentation.
+To get the code, and be able to push changes back to the main project, you'll need to (1) fork the repository on github and (2) clone the repository to your local machine.
 
-## Writing Tests
+This is very straight forward if you're using [GitHub's CLI][]:
 
-If you are adding a new function to scPortrait please also include a unit test.
+```console
+$ gh repo fork mannlabs/scPortrait --clone --remote
+```
 
-## Running Tests
+This will fork the repo to your github account, create a clone of the repo on your current machine, add our repository as a remote, and set the `main` development branch to track our repository.
 
-We use [pytest][] to test scProtrait. To run the tests, simply run `pytest .` in your local clone of the scPortrait repo.
+To do this manually, first make a fork of the repository by clicking the "fork" button on our main github package. Then, on your machine, run:
 
-A lot of warnings can be thrown while running the test files. It’s often easier to read the test results with them hidden via the `--disable-pytest-warnings`  argument.
+```console
+$ # Clone your fork of the repository (substitute in your username)
+$ git clone https://github.com/{your-username}/scPortrait.git
+$ # Enter the cloned repository
+$ cd scPortrait
+$ # Add our repository as a remote
+$ git remote add upstream https://github.com/mannlabs/scPortrait.git
+$ # git branch --set-upstream-to "upstream/main"
+```
 
-## Building the Documentation
+### setting up `pre-commit`
 
-The docs for scPortrait are updated and built automatically whenever code is merged or commited to the main branch. To test documentation locally you need to do the following:
+We use [pre-commit][] to run some styling checks in an automated way.
+We also test against these checks, so make sure you follow them!
 
-1. navigate into the `docs` folder in your local scPortrait clone
-2. ensure you have a functional development environment where the additional dev dependencies (these incldue those required to build the documentation) are installed
-3. execute:
+You can install pre-commit with:
 
 ```console
-make clean
-make html
+$ pip install pre-commit
 ```
-4. open the file `scportriat/docs/_build/html/index.html` in your favorite browser
 
-## Tutorials with jupyter notebooks
+You can then install it to run while developing here with:
 
-Indepth tutorials using jupyter notebooks are hosted in a dedicated repository: [scPortrait Notebooks](https://github.com/MannLabs/scPortrait-notebooks).
+```console
+$ pre-commit install
+```
 
-Please update and/or add new tutorials there.
+From the root of the repo.
+
+If you choose not to run the hooks on each commit, you can run them manually with `pre-commit run --files={your files}`.
 
-## Commiting Code Changes
+### Creating a branch for your feature
 
-We assume some familiarity with `git`. For more detailed information we recommend checking out these tutorials:
+All development should occur in branches dedicated to the particular work being done.
+Additionally, unless you are a maintainer, all changes should be directed at the `main` branch.
+You can create a branch with:
 
-[Atlassian's git tutorial][]: Beginner friendly introductions to the git command line interface
-[Setting up git for GitHub][]: Configuring git to work with your GitHub user account
+```console
+$ git checkout main                 # Starting from the main branch
+$ git pull                          # Syncing with the repo
+$ git switch -c {your-branch-name}  # Making and changing to the new branch
+```
 
 ### Commit Message Guidelines
 
 To keep the commit history clear and easy to navigate, we use short, descriptive commit messages with a conventional prefix indicating the type of change:
 
 `[TAG] Short, clear description in imperative form`
 
+Following this style is encouraged for all contributions, but do not worry if you forget — maintainers may adjust commit messages during PR squash-merge.
+
 #### Format
 - **Use the imperative mood** (“Fix bug”, “Add feature”), not past tense.
 - **Keep it brief** (ideally under 60 characters).
@@ -118,101 +150,120 @@ To keep the commit history clear and easy to navigate, we use short, descriptive
 | Update docs | `[DOCS] Expand documentation for project setup` |
 | Ensure dtypes are consistent over all image tiles during stitching | `[FIX] Ensure dtype consistency across stitched tiles` |
 
-#### Why This Helps
+### Open a pull request
 
-- Makes pull request histories easy to scan
-- Helps auto-generate release notes with meaningful summaries
-- Avoids noise and ambiguity
-- Works well with automated tools (e.g., GitHub Release Notes)
+When you're ready to have your code reviewed, push your changes up to your fork:
 
-Following this style is encouraged for all contributions, but do not worry if you forget — maintainers may adjust commit messages during PR squash-merge.
+```console
+$ # The first time you push the branch, you'll need to tell git where
+$ git push --set-upstream origin {your-branch-name}
+$ # After that, just use
+$ git push
+```
 
-### Forking and cloning
+And open a pull request by going to the main repo and clicking *New pull request*.
+GitHub is also pretty good about prompting you to open PRs for recently pushed branches.
 
-To get the code, and be able to push changes back to the main project, you'll need to (1) fork the repository on github and (2) clone the repository to your local machine.
+We'll try and get back to you soon!
 
-This is very straight forward if you're using [GitHub's CLI][]:
 
-```console
-$ gh repo fork mannlabs/scPortrait --clone --remote
-```
+## Code-style
 
-This will fork the repo to your github account, create a clone of the repo on your current machine, add our repository as a remote, and set the `main` development branch to track our repository.
+This project uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either automatically fix issues with the code, or raise an error message.
 
-To do this manually, first make a fork of the repository by clicking the "fork" button on our main github package. Then, on your machine, run:
+To enable pre-commit locally, simply run
 
 ```console
-$ # Clone your fork of the repository (substitute in your username)
-$ git clone https://github.com/{your-username}/scPortrait.git
-$ # Enter the cloned repository
-$ cd scPortrait
-$ # Add our repository as a remote
-$ git remote add upstream https://github.com/mannlabs/scPortrait.git
-$ # git branch --set-upstream-to "upstream/main"
+pre-commit install
 ```
 
-### setting up `pre-commit`
+in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time.
 
-We use [pre-commit][] to run some styling checks in an automated way.
-We also test against these checks, so make sure you follow them!
+Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. If you didn't run `pre-commit` before pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message.
 
-You can install pre-commit with:
+If pre-commit.ci added a commit on a branch you still have been working on locally, simply use
 
 ```console
-$ pip install pre-commit
+git pull --rebase
 ```
+to integrate the changes into yours.
 
-You can then install it to run while developing here with:
+While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage.
 
-```console
-$ pre-commit install
-```
+## Writing documentation
 
-From the root of the repo.
+Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features:
 
-If you choose not to run the hooks on each commit, you can run them manually with `pre-commit run --files={your files}`.
+-   Google-style docstrings, where the __init__ method should be documented in its own docstring, not at the class level.
+-   there should be no specification of type in the docstrings (this should be done in the function call with mypy style type hints instead)
+-   add type hints for use with mypy
+-   example code
+-   automatic building with Sphinx
 
-### Creating a branch for your feature
+Refer to [sphinx google style docstrings][] for detailed information on writing documentation.
 
-All development should occur in branches dedicated to the particular work being done.
-Additionally, unless you are a maintainer, all changes should be directed at the `main` branch.
-You can create a branch with:
+## Building the Documentation
+
+The docs for scPortrait are updated and built automatically whenever code is merged or commited to the main branch. To test documentation locally you need to do the following:
+
+1. navigate into the `docs` folder in your local scPortrait clone
+2. ensure you have a functional development environment where the additional dev dependencies (these incldue those required to build the documentation) are installed
+3. execute:
 
 ```console
-$ git checkout main                 # Starting from the main branch
-$ git pull                          # Syncing with the repo
-$ git switch -c {your-branch-name}  # Making and changing to the new branch
+make clean
+make html
 ```
+4. open the file `scportriat/docs/_build/html/index.html` in your favorite browser
 
-### Open a pull request
+## Writing Tests
 
-When you're ready to have your code reviewed, push your changes up to your fork:
+If you introduce a new function or modify existing functionality, be sure to include corresponding **unit tests**. Tests help ensure correctness, stability, and maintainability across the codebase.
+
+## Running Tests
+
+scPortrait uses [pytest][] for testing and maintains two categories of test suites:
+1.  Unit Tests
+2.  End-to-End (E2E) Tests
+
+Unit Tests are run whenever a commit is made in a PR. Before opening a pull request, ensure **unit tests pass locally**.
+
+The E2E tests are computationally more expensive and run the entire scPortrait processing pipeline and as such are much slower. These tests are only run on commits made in the main branch e.g. upon merging a PR. Before merging into `main`, please ensure **E2E tests pass**.
+
+A lot of warnings can be thrown while running the test files. It’s often easier to read the test results with them hidden via the `--disable-pytest-warnings`  argument.
 
+### Unit Tests
+
+Unit tests validate individual functions or modules in isolation (e.g., file readers, plotting utilities, segmentation helpers). These tests are designed to be fast and run frequently during development.
+
+Run only unit tests:
 ```console
-$ # The first time you push the branch, you'll need to tell git where
-$ git push --set-upstream origin {your-branch-name}
-$ # After that, just use
-$ git push
+pytest tests/unit_tests --disable-warnings
 ```
 
-And open a pull request by going to the main repo and clicking *New pull request*.
-GitHub is also pretty good about prompting you to open PRs for recently pushed branches.
-
-We'll try and get back to you soon!
+### End-to-End (E2E) Tests
 
-## Creating a development Environment
+E2E tests run larger workflow scenarios to ensure that multiple components of the pipeline work correctly together (e.g., segmentation → extraction → featurization → selection).
+These tests are **much slower** and may require larger example data.
 
-It's recommended to do development work in an isolated environment.
-There are number of ways to do this, including virtual environments, conda environments, and virtual machines.
+Run only E2E tests:
+```console
+pytest tests/e2e_tests --disable-warnings
+```
 
-We use conda environments. To setup a conda environment please do the following:
+### Running All Tests
 
+To run both unit and E2E tests together:
 ```console
-conda create -n "{dev_environment_name}" python=3.12
-conda activate {dev_environment_name}
-pip install scportrait[dev]
+pytest .
 ```
 
+## Tutorials with jupyter notebooks
+
+Indepth tutorials using jupyter notebooks are hosted in a dedicated repository: [scPortrait Notebooks](https://github.com/MannLabs/scPortrait-notebooks).
+
+Please update and/or add new tutorials there.
+
 ## Creating a New Release
 
 Before creating a release, ensure that **all tests pass** for the code currently on `main` (unit tests and end-to-end tests). If any tests fail, fix the issues before proceeding.