Introduced developer guide, moved pre-commit information to this guide

Author: kopperp

.pre-commit-config.yaml

@@ -11,6 +11,28 @@ repos:
         name: ruff linter
         alias: lint
       # Run the formatter
-      - id: ruff-format
-        name: ruff formatter
-        alias: format
+      # - id: ruff-format
+      #   name: ruff formatter
+      #   alias: format
+
+  - repo: https://github.com/jendrikseipp/vulture
+    # Vulture version
+    rev: v2.15
+    hooks:
+      # Run dead code detection
+      # Paths are configured under [tool.vulture] in pyproject.toml
+      - id: vulture
+        name: vulture dead code
+        alias: vulture
+
+  # ty has no official pre-commit hook yet (https://github.com/astral-sh/ty/issues/269).
+  # Run it as a local hook using the system-installed binary
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty type checker
+        alias: ty
+        entry: ty check --color always --project pyhope pyhope
+        language: system
+        pass_filenames: false
+        types: [python]

README.md

@@ -198,73 +198,6 @@ with Mesh('1-01-cartbox_mesh.h5') as m:
     lobatto_nodes = Basis.legendre_gauss_lobatto_nodes(order=m.nGeo)
 ```
     
-## Ruff linter and formatter
-
-PyHOPE uses [Ruff](https://docs.astral.sh/ruff/) for code linting and formatting of all .py files to maintain consistent code quality and style.
-Ruff is a fast Python linter and formatter that combines multiple individual tools like flake8, black, isort, etc.
-
-### Pre-commit Integration
-
-Ruff is integrated with [pre-commit](https://pre-commit.com/) to automatically check and format code before each commit. The configuration is defined in `.pre-commit-config.yaml` and includes:
-
-1. Ruff linter hook
-2. Ruff formatter hook
-
-All hooks can be tested with pre-commit before commiting your changes with
-```
-pre-commit run
-```
-Note that all pre-commit hooks only run on files that have been staged. The pre-commit hooks can be ignored with the additional flag
-```
---no-verify
-```
-
-When creating a commit:
-1. The linter displays errors immediately
-2. The formatter
-   - Fails if it finds issues
-   - Applies automatic fixes
-   - Unstages the modified files
-
-After formatter changes:
-- Review the applied changes
-- Re-stage the files
-- Try committing again (formatter should pass if no new changes were made)
-
-Some linter errors can be fixed automatically with
-```
-ruff check --fix
-```
-while others require manual corrections.
-Note that the flag `--unsafe-fixes` can change the functionality of the code, while `--fix` should keep it.
-
-### Ruff configuration
-
-Ruff's configuration is managed through the `pyproject.toml` file in the project root and specifies linting rules, checks, excludes, etc.
-
-To suppress a violation inline, Ruff uses a `noqa` system similar to Flake8. To ignore an individual violation, add `# noqa: {code}` to the end of the line, like so:
-```
-# Ignore F841.
-x = 1  # noqa: F841
-# Ignore E741 and F841.
-i = 1  # noqa: E741, F841
-# Ignore _all_ violations.
-x = 1  # noqa
-```
-
-Similar to the linter it is also possible to ignore code blocks for the formatter with
-```
-# fmt: off
-_code_
-# fmt: on
-```
-or a python specific block with
-```
-if condition: # fmt: skip
-```
-
-```
-
 # Cite
 This is a scientific project. If you use PyHOPE for publications or presentations in science, please support the project by citing the following article.
 ```bibtex

docs/developer-guide/get-the-source.md

@@ -0,0 +1,99 @@
+# Environment Setup
+
+Get the source and start developing
+
+---
+
+## Obtaining the Source
+
+PyHOPE uses [git](https://git-scm.com) to sync down source code. Some larger mesh files are stored in [Git LFS](https://git-lfs.com). `git-lfs` must be installed before cloning, otherwise those files will be replaced by pointer stubs.
+
+!!! info
+    PyHOPE developers commonly put their virtual environment in `venv` within the git repository. All commands in this document assume that your virtual environment is in `venv`.
+
+```bash
+git clone https://github.com/hopr-framework/PyHOPE.git
+cd PyHOPE
+python -m venv venv
+source venv/bin/activate
+python -m pip install --upgrade -e .
+```
+
+!!! info
+    Changes in the source code are immediately reflected within the virtual environment without any explicit sync requirement.
+
+## Linting
+
+PyHOPE enforces code quality through three static analysis tools which are wired up as [pre-commit](https://pre-commit.com/) hooks and run as the first stage of the CI pipeline.
+
+### Tools
+
+**[Ruff](https://docs.astral.sh/ruff/)** is a fast Python linter that consolidates the roles of `flake8`, `black`, `isort`, and many others in a single tool. It checks style and common errors across all `.py` files.  
+
+!!! note
+    Some linter errors can be fixed automatically:
+    ```bash
+    ruff check --fix
+    ```
+    Note that `--unsafe-fixes` may silently change program behaviour; `--fix` is guaranteed to be behaviour-preserving.
+
+**[ty](https://github.com/astral-sh/ty)** is a static type checker by Astral. It resolves all imports against the full installed dependency set.
+
+**[vulture](https://github.com/jendrikseipp/vulture)** detects dead code such as unused functions, unreachable branches, and variables that are assigned but never read.
+
+### Pre-commit Integration
+
+All three tools are configured as hooks in `.pre-commit-config.yaml`. Install them once after cloning.
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+From that point on, every `git commit` runs ruff, vulture, and ty against the staged files automatically. To run all hooks explicitly against the full codebase.
+
+```bash
+pre-commit run --all-files
+```
+To skip the hooks for a specific commit, pass `--no-verify` to `git commit`. Use this sparingly as the CI pipeline enforces the same rules and will catch anything skipped locally.
+
+!!! note
+    [ty](https://github.com/astral-sh/ty) does not yet have an official pre-commit hook ([astral-sh/ty#269](https://github.com/astral-sh/ty/issues/269)). The local hook in `.pre-commit-config.yaml` calls the system-installed `ty` binary directly. Make sure `ty` is installed in your virtual environment (`pip install ty`) before committing.
+
+### Ruff Configuration
+
+Ruff's rules, exclusions, and per-file overrides are managed through `pyproject.toml` in the project root. To suppress a specific violation on a single line, use a `# noqa` comment with the rule code:
+
+```python
+x = 1        # noqa: F841        # suppress unused-variable for this line only
+i = 1        # noqa: E741, F841  # suppress multiple rules
+x = 1        # noqa              # suppress all violations on this line
+```
+
+!!! note
+    Use inline suppressions only when the violation is a known false positive or an intentional deviation. Document the reason in a comment where it is not obvious.
+
+## Continuous Integration
+
+PyHOPE runs a CI pipeline on every pull request. Only one pipeline run executes at a time per branch; a newer push cancels any run still in progress. The pipeline is structured in three stages that run in order.
+
+**1. Lint**
+
+The three tools described above run in parallel. All three must pass before the compatibility stage begins. Running `git commit` locally triggers the same checks automatically via pre-commit.
+
+**2. Compatibility**
+
+A matrix job runs the mesh generation pipeline against five Python versions: **3.10 – 3.14**. All versions run in parallel, so a failure on one version does not abort the others. Two representative tutorials are executed end-to-end:
+
+```bash
+pyhope tutorials/1-04-cartbox_multiple_stretch/parameter.ini
+pyhope tutorials/2-02-external_mesh_CGNS_mixed/parameter.ini
+```
+
+**3. Verification**
+
+| Job             | Description                                                                                                                                                                   |
+| ---             | ---                                                                                                                                                                           |
+| **examples**    | Runs the full tutorial suite with coverage instrumentation                                                                                                                    |
+| **healthcheck** | Runs PyHOPE's internal health checks: `coverage run -m pyhope --verify tutorials`                                                                                             |
+| **convergence** | Runs FLEXI solver convergence tests in a dedicated Fedora container (`ghcr.io/hopr-framework/nrg-fedora`). Requires `GITHUB_TOKEN` to pull from the GitHub Container Registry |
+| **coverage**    | Merges `coverage.xml` artifacts from `examples` and `healthcheck`. On PRs targeting `main`, a bot posts a summary comment. Thresholds: **85% overall**, **90% for new code**  |

docs/developer-guide/github-workflow.md

@@ -0,0 +1,52 @@
+# GitHub workflow
+
+Overview of the development workflow
+
+---
+
+Code development is performed on [GitHub](https://github.com), with a protected `main` branch. The actual development is performed on feature branches, which are merged to `main` following a pull request and the completion of a code review. Continuous Integration (CI) tests are automatically performed on pull requests with a successful pass as a prerequisite for merging into `main`.
+
+## Issues & Milestones
+Issues are created for bugs, improvements, features, regression testing and documentation. The issues should be named with a few keywords. Try to avoid describing the complete issue already in the title. The issue can be assigned to a certain milestone (if appropriate).
+
+Milestones are created based on planned releases (e.g. Release 1.2.1) or as a grouping of multiple related issues (e.g. Documentation Version 1, Clean-up Emission Routines). A deadline can be given if applicable. The milestone should contain a short summary of the work performed (bullet-points) as its contents will be added to the description of the releases. Generally, pull requests should be associated with a milestone containing a release tag, while issues should be associated with the grouping milestones.
+
+As soon as a developer wants to start working on an issue, she/he shall assign himself to the issue and a branch and pull request denoted as work in progress ("draft") should be created to allow others to contribute and track the progress. Ideally, issues should be created for every code development for documentation purposes. Branches without an issue should be avoided to reduce the number of orphaned/stale branches. Where a branch must be created outside the issue context, its name should carry a prefix that matches one of the existing GitHub labels
+
+```
+bugfix.connect.internal
+feature.sort.hilbertmorton
+improvement.extrude.zones
+```
+
+Pull requests should include a concise description of what changed and why, a reference to the issue being resolved (e.g. `Closes #42`), and a note on anything that reviewers should pay particular attention to.
+
+## Code Review
+Every pull request requires at least one approving review before it can be merged. Reviewers should check at least the following points.
+
+- The implementation is correct and consistent with the existing architecture
+- New code follows the conventions in the [Style Guide](style-guide.md)
+- Public functions carry type annotations and docstrings
+- New functionality is covered by tests or tutorials
+- The CI pipeline passes all checks without errors or warnings
+
+Authors should respond to review comments promptly. If a comment is addressed by a code change, mark it as resolved. If it is addressed by explanation, reply in the thread and leave it for the reviewer to close.
+
+## Commit Messages
+Commit messages should be written in the imperative mood and describe *what* the commit does, not *what was done*:
+
+```
+# Good
+Add convergence test for CGNS mixed mesh
+
+# Avoid
+Added convergence test
+Fixed stuff
+```
+
+
+## Release and Deploy
+
+Releases follow [Semantic Versioning](https://semver.org): `MAJOR.MINOR.PATCH`. A new release is created from `main` by opening a pull request associated with the corresponding release milestone. Once merged, navigate to [Releases](https://github.com/hopr-framework/PyHOPE/releases) and select `Draft a new release`. Set the tag to `vMAJOR.MINOR.PATCH` and the title to `Release MAJOR.MINOR.PATCH`. The milestone description supplies the release notes.
+
+Tagged releases are automatically packaged as a Python wheel and deployed to [PyPI](https://pypi.org/project/PyHOPE) by the CI pipeline.

docs/developer-guide/index.md

@@ -0,0 +1,16 @@
+# Contributing to PyHOPE
+
+How to get started as a developer
+
+---
+
+This guide describes how to develop PyHOPE. It covers the workflow, tooling, and conventions that keep the codebase consistent as the project grows.
+
+
+The project is developed openly on GitHub under the GPL-3.0 license. Contributions of all kinds are welcome - bug reports, documentation improvements, new features, and convergence tests.
+
+**Contents**
+
+- [GitHub Workflow](github-workflow.md): Branch strategy, pull requests, code review, and release process
+- [Environment Setup](get-the-source.md): Cloning, virtual environment, linting tools, and the CI pipeline
+- [Style Guide](style-guide.md): Coding conventions, naming rules, and documentation standards