Contributing to ADELM

Thanks for your interest in ADELM.

ADELM is still evolving quickly, so contributions do not need to fit a rigid template. What helps most is keeping changes clear, well-scoped, and well-explained. This page gives a lightweight guide for reporting issues, proposing changes, and contributing code or documentation.

Reporting issues

Please report bugs and open discussions on the issue tracker.

Issues are useful for more than bugs. They can also be used to discuss:

  • process formulations

  • parameterization choices

  • diagnostics and evaluation workflows

  • documentation gaps

  • implementation bugs or inconsistencies

When opening an issue, try to include:

  • what you observed

  • why it matters

  • the files, modules, or workflows involved

  • a minimal example, config, figure, or log if available

For process-related issues, it is often helpful to be explicit about whether the concern is:

  • a bug

  • a design choice

  • a simplification that should be documented more clearly

  • a comparison point with another model or method

Development workflow

There is no need to overcomplicate the workflow. In most cases:

  1. Create a branch for the change.

  2. Keep the scope reasonably focused.

  3. Use commit messages that describe what changed.

  4. Open a merge request or pull request with a short explanation.

For larger changes, it helps to discuss the direction in an issue first, especially when the change affects:

  • process equations

  • parameterization logic

  • runtime configuration

  • variable naming or registry structure

  • diagnostics or benchmark workflows

Code style

ADELM code does not need to look “clever”; it needs to stay readable.

Please try to:

  • use clear names for variables, parameters, states, and fluxes

  • keep process logic explicit, especially in physics modules

  • update docstrings and comments when assumptions change

  • avoid introducing new terminology when existing project terms already work

If a change introduces new diagnostics, parameters, or fluxes, please also update the relevant variable definitions and documentation.

Documentation

Documentation is part of the contribution, not an afterthought.

In practice, that usually means updating one or more of:

  • README.md for repository-level structure

  • the user guide for usage and workflow changes

  • the physics and neurals for model concepts and formulations

  • the variable tables for registry-backed parameter/variable docs

If you change a process module, try to document:

  • what changed

  • which assumptions are retained

  • which diagnostics or balance terms are affected

Merge requests / pull requests

A good merge request or pull request usually includes:

  • a short summary of the change

  • the main files or modules affected

  • notes on tests, plots, or diagnostics used to check the change

  • documentation updates when relevant

For process-heavy changes, a short changelog-style summary can be especially helpful, for example:

  • Added

  • Changed

  • Fixed

  • Deleted

License

By contributing to ADELM, you agree that your contributions will be licensed under the European Union Public Licence v1.2 (EUPL), the same licence that covers the project.