Develop with Neptoon

Thanks for your interest in developing neptoon! Whether you want to fix a bug, add a feature, or contribute a new correction, this page points you to everything you need.

Most of our internal development happens on our institution's GitLab instance (https://codebase.helmholtz.cloud/cosmos/neptoon). We are very open to outside contributions, which go through our public mirror at gitlab.com/neptoon/neptoon. The mirror tracks the main and development branches, so a fork from there is always up to date.

How to contribute

For external contributions, fork the public mirror at gitlab.com/neptoon/neptoon. The public repository mirrors the main and development branches, so forks should start from a current code base.

Before opening a merge request:

1. Create a focused branch from development.
2. Add or update tests for behaviour changes.
3. Update user documentation for configuration, CLI, or workflow changes.
4. Run the relevant test subset locally.
5. Keep scientific algorithm changes separate from packaging, CI, or documentation-only changes when possible.

For larger contributions, contact contact@neptoon.org before investing substantial work.

The full contribution guide lives in CONTRIBUTING.md. It walks you through:

• setting up your environment with uv,
• our code standards (formatting, linting, docstrings, tests),
• the verb-first lower-case snake_case function-naming convention documented in agent/conventions/function_naming.md,
• and how to submit your work as a merge request.

The codebase at a glance

Start with the software architecture page for the canonical layer and component diagrams, or open its interactive map to search and explore dependencies.

Once you have cloned the repository, these files get you (and your AI coding assistant) oriented quickly:

• AGENTS.md: a single-page technical overview (toolchain, commands, where everything lives).
• agent/architecture.md: the pipeline flow and package map.
• agent/conventions/: the detailed conventions. These are the source of truth for how neptoon is built, so read the relevant one before a non-trivial change.

Working with an LLM?

The files above are written so that AI coding assistants can read them too. Point your assistant at AGENTS.md and the relevant convention, and it will have what it needs to write code that fits neptoon.

Adding a new correction

Adding a correction is one of the most common ways to extend neptoon, and there are two paths depending on your goal:

• Use a custom correction in your own analysis, without changing neptoon itself: see Write Your Own Corrections.
• Contribute a correction to neptoon so it becomes part of the standard pipeline for everyone: see Adding a Correction to neptoon.

Documentation expectations for new functionality

Not every new function needs a hand-written user-guide page. Private helpers, lazy imports, and implementation details are covered by tests and docstrings. User-facing changes should be documented where users will look first:

Change type	Documentation expected
New CLI command or option	User guide page or command example, plus README mention when it is a primary workflow.
New YAML field or accepted value	Relevant config reference page and at least one example YAML when practical.
New public notebook/helper function	Short user-guide section or notebook example, plus docstring/API reference.
New scientific method or correction	User guide explanation, method reference/citation, config example, and tests.
Internal helper, refactor, or private function	Docstring if non-obvious; no separate user docs required.

When a feature appears in CHANGELOG.md under Added or changes expected user behaviour under Changed, check that at least one user-facing document, example, or generated API reference gives users enough information to try it.

Questions?

For anything not covered here, email contact@neptoon.org.