aiidateam · GeigerJ2 · Mar 6, 2026 · Mar 6, 2026 · Mar 6, 2026 · Mar 9, 2026
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,45 @@
+# Contributing to AiiDA
+
+Thanks for your interest in contributing to AiiDA!
+
+## Getting started
+
+1. Fork and clone the repository
+1. Install development dependencies: `uv sync` (creates a `.venv` and installs all dependencies)
+1. Create a branch: `git switch -c feature/123/short-description`
+1. Make your changes and ensure pre-commit passes: `uv run pre-commit run -a` (runs on all files, safer for mypy since changes in one file can cause errors in others)
+1. Run relevant tests: `uv run pytest tests/path/to/test_file.py` (use `-n auto` for parallel execution, `-m presto` to run only tests marked with `@pytest.mark.presto` — these require no external services; add this marker to new tests that don't need PostgreSQL or RabbitMQ)
+1. Push and open a pull request against `main`
+
+## Development guide
+
+See [`AGENTS.md`](AGENTS.md) for comprehensive development documentation, including:
+
+- Project architecture and source layout
+- Code style and pre-commit hooks
+- Testing conventions and commands
+- Branching, versioning, and commit style
+- Common patterns (adding nodes, CalcJobs, WorkChains, CLI commands)
+- Debugging tips
+
+## Quick reference
+
+| Task | Command |
+|------|---------|
+| Install dependencies | `uv sync` |
+| Run quick tests | `uv run pytest -m presto -n auto` |
+| Run full test suite | `uv run pytest` |
+| Run pre-commit (staged files) | `uv run pre-commit run` |
+| Run pre-commit (all files) | `uv run pre-commit run -a` |
+| Build docs | `uv run sphinx-build -b html docs/source docs/build/html` |
+
+## Reporting issues
+
+- Use [GitHub Issues](https://github.com/aiidateam/aiida-core/issues) to report bugs or request features
+- Check existing issues before creating a new one
+- Include a minimal reproducible example when reporting bugs
+
+## Code of conduct
+
+Please be respectful and constructive in all interactions.
+See [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -47,7 +47,6 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = [
-    'developer_guide/**',
     'import_export/**',
     'internals/global_design.rst',
     'reference/apidoc/**',

diff --git a/docs/source/developer_guide/code_review.md b/docs/source/developer_guide/code_review.md
@@ -0,0 +1,67 @@
+# Code review guidelines
+
+## Standards
+
+- Technical facts and data overrule personal preferences.
+- Don't block a PR over minor stylistic preferences — but do request changes for issues you are aware of.
+- Be responsive to review requests.
+  AiiDA users who put in the effort of contributing back deserve our attention the most, and timely review is a big motivator.
+- Look at every line of code that is being modified.
+
+## Communication
+
+- Offer encouragement for things done well, don't just point out mistakes.
+- Fine to mention what could be improved but is not mandatory -- prefix such comments with "Nit:" for "nitpick".
+- Share knowledge that helps the submitter improve their understanding of the code.
+  Clarify where you do or don't expect action.
+
+## Checklist
+
+### Scope
+
+- Are you being asked to review more than ~400 lines of code?
+  Don't be shy to ask the submitter to split the PR -- review effectiveness [drops substantially beyond a few hundred lines](https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/).
+- Are there parts of the codebase that have not been modified but *should* be adapted to the changes?
+- Does the code change require a documentation update?
+
+### Design
+
+- Is the PR focused on a single issue?
+- Does this change belong in the codebase?
+- Is it well-integrated?
+
+### Functionality
+
+- Does the code do what the developer intended?
+- Are there edge cases where it could break?
+- Ideally, dogfood new features during review (check out the branch and try them) -- this is difficult to assess from code alone.
+
+### Complexity
+
+- Any complex lines, functions, or classes that are not easy to understand?
+- Over-engineering: is the code too complex for the problem at hand?
+
+### Tests
+
+- Are there tests for new functionality?
+- For bug fixes: is there a test that breaks if the bug resurfaces?
+- Are the tests correct, useful, and easy to understand?
+
+### Naming
+
+- Good names are long enough to communicate what the item does, without being so long that they become hard to read.
+
+### Comments
+
+- Do comments explain *why* code exists rather than *what* it is doing?
+
+### Style and consistency
+
+- Does the contribution follow AiiDA {doc}`coding style <coding_style>` (mostly enforced automatically via pre-commit hooks)?
+- Prefix style suggestions with "Nit:".
+
+## Sources
+
+- [Google Engineering Practices](https://google.github.io/eng-practices/review/reviewer/standard.html)
+- [SmartBear: Best Practices for Peer Code Review](https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/)
+- [Code Review Guidelines for Humans](https://phauer.com/2018/code-review-guidelines/)
diff --git a/docs/source/developer_guide/coding_style.md b/docs/source/developer_guide/coding_style.md
@@ -0,0 +1,110 @@
+# Coding style
+
+If you follow the instructions to {doc}`set up your development environment <development_environment>`, the AiiDA coding style is largely **enforced automatically using pre-commit hooks** (configured in `.pre-commit-config.yaml`).
+Run `uv run pre-commit run` to check staged files, or `uv run pre-commit run --all-files` to check everything.
+
+This document mainly acts as a reference.
+
+## Pre-commit hooks overview
+
+The following hooks run automatically on staged files (see `.pre-commit-config.yaml` for the full configuration):
+
+**Formatting and linting** ([ruff](https://docs.astral.sh/ruff/)):
+
+- `ruff format` — auto-formats code (single quotes, PEP 8 compliance)
+- `ruff` — linting with rule sets: `E`/`W` (pycodestyle), `F` (pyflakes), `I` (isort), `N` (pep8-naming), `PLC`/`PLE`/`PLR`/`PLW` (pylint), `RUF` (ruff-specific), `FLY` (f-string enforcement), `NPY201` (NumPy 2.0 compatibility)
+
+**Type checking:**
+
+- `mypy` — static type checking (many files are currently excluded; see below)
+
+**File checks:**
+
+- `check-merge-conflict`, `check-added-large-files`, `check-yaml` — basic file validation
+- `double-quote-string-fixer` — converts double quotes to single quotes
+- `end-of-file-fixer`, `trailing-whitespace`, `mixed-line-ending` — whitespace normalization
+- `fix-encoding-pragma` — removes outdated `# -*- coding: utf-8 -*-` lines
+
+**Dependency and project maintenance:**
+
+- `uv-lock` — validates lockfile consistency
+- `pretty-format-toml`, `pretty-format-yaml` — auto-format TOML/YAML files
+- `nbstripout` — strips output from Jupyter notebooks
+- `imports` — auto-generates `__all__` imports for `src/aiida/`
+- `generate-conda-environment`, `validate-conda-environment` — keeps `environment.yml` in sync with `pyproject.toml`
+- `verdi-autodocs` — auto-generates verdi CLI documentation
+
+## General rules
+
+- Code should conform to [PEP 8](https://peps.python.org/pep-0008/).
+- When compatible, follow the [Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md).
+
+## AiiDA-specific conventions
+
+### File operations
+
+- When opening a general file for reading or writing, use [`open()`](https://docs.python.org/3/library/functions.html#open) as a context manager with UTF-8 encoding for formatted files, e.g., `with open(path, 'w', encoding='utf8') as handle:`.
+- When opening a file from a node's file repository, use the `Node.base.repository` interface (e.g., `node.base.repository.open('filename')`).
+
+### Source file headers
+
+Each source file should start with the following copyright header:
+
+```python
+###########################################################################
+# Copyright (c), The AiiDA team. All rights reserved.                     #
+# This file is part of the AiiDA code.                                    #
+#                                                                         #
+# The code is hosted on GitHub at https://github.com/aiidateam/aiida-core #
+# For further information on the license, see the LICENSE.txt file        #
+# For further information please visit http://www.aiida.net               #
+###########################################################################
+```
+
+## Python style
+
+### F-strings
+
+Prefer f-strings over `.format()` or `%` formatting:
+
+```python
+value = 'test'
+f'Variable {value}'
+
+a = 1
+b = 2
+f'{a} + {b} = {a + b}'  # '1 + 2 = 3'
+```
+
+F-strings are easier to read, save characters, and are more efficient.
+One exception: when you have a string with many placeholders, it is acceptable to use `.format(**dictionary)`.
+
+**Logging calls** are another exception — use `%` formatting so string interpolation is deferred until the message is actually emitted:
+
+```python
+# Preferred — interpolation is skipped if the log level is disabled
+logger.info('Processing node %s', node.pk)
+
+# Not ideal — string is always constructed, regardless of log level
+logger.info(f'Processing node {node.pk}')
+```
+
+### Pathlib
+
+Prefer [`pathlib`](https://docs.python.org/3/library/pathlib.html) over `os.path` for file and folder manipulation.
+This is not currently enforced; legacy `os.path` usage exists throughout the codebase.
+Refer to the official documentation for a [translation table between os and pathlib](https://docs.python.org/3/library/pathlib.html#corresponding-tools).
+
+### Type hinting
+
+Add [type hints](https://docs.python.org/3/library/typing.html) to new code and update existing code when possible.
+Type hints allow static type checkers to validate the code and IDEs to provide improved auto-completion.
+They also make the code easier to read and serve as verified documentation of the API contract.
+
+The pre-commit hooks include [mypy](https://mypy-lang.org/) for type checking.
+CI runs the same pre-commit hooks, so it catches anything missed locally.
+
+:::{note}
+`mypy` runs in pre-commit/CI but various legacy files are currently excluded (see the `exclude` list for the `mypy` hook in `.pre-commit-config.yaml`).
+New files are checked by default.
+:::
diff --git a/docs/source/developer_guide/core.rst b/docs/source/developer_guide/core.rst