# How to Contribute to WeatherNext: A Complete Guide to Open-Source Contributions

> Learn how to contribute to WeatherNext with this guide. Sign the CLA, fork the repo, follow coding standards, run tests, and submit your pull request to the google-deepmind/weathernext project.

- Repository: [Google DeepMind/weathernext](https://github.com/google-deepmind/weathernext)
- Tags: how-to-guide
- Published: 2026-08-16

---

**To contribute to WeatherNext, you must sign the Google CLA, fork the repository, follow JAX/Haiku coding patterns in the core architecture files, run the test suite locally, and submit a pull request for maintainer review.**

Contributing to **WeatherNext**—Google DeepMind's open-source weather forecasting system—requires understanding its JAX-based architecture and specific design conventions. This guide walks through the complete contribution workflow, from legal requirements to practical code examples based on the actual repository structure.

## Sign the Contributor License Agreement (CLA)

Every contributor to WeatherNext must have a signed **Google Contributor License Agreement** before any code can be merged. This requirement is enforced at the repository level and automatically tracked via GitHub.

Visit [cla.developers.google.com](https://cla.developers.google.com/) to view or sign your agreement. The repository's [`CONTRIBUTING.md`](https://github.com/google-deepmind/weathernext/blob/main/CONTRIBUTING.md) explicitly documents this dependency—your PR will be blocked if the CLA check fails.

The WeatherNext project uses the **Apache 2.0 license** for code and **CC-BY 4.0** for documentation and other content. Any code you contribute will be released under Apache 2.0.

## Fork, Clone, and Branch the Repository

Start by creating your development environment:

```bash
git clone https://github.com/google-deepmind/weathernext.git
cd weathernext
git checkout -b my-feature

```

Keep each branch focused on a single logical change—whether that's a new model component, a bug fix, or documentation improvement. The maintainers review PRs for atomicity, and sprawling changes are harder to merge.

## Follow WeatherNext Code Style and Architecture Patterns

WeatherNext's core implementation relies on specific design patterns that new contributions must respect. The **multimodality forward pass** lives in [`weathernext/weathernext2/architecture.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture.py), with helper utilities in [`weathernext/weathernext2/architecture_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture_utils.py).

When extending functionality, adhere to these three architectural conventions:

- **Modality classification** — Use `classify_input_data` to separate global from grid data. This function in [`architecture_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/architecture_utils.py) (lines 29-71) determines how input tensors are routed through the model.

- **Data merging** — Call `merge_global_data` to combine global conditioning features with per-grid data (lines 74-84 of [`architecture_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/architecture_utils.py)).

- **Typed-graph construction** — Follow the patterns in [`utils/typed_graph.py`](https://github.com/google-deepmind/weathernext/blob/main/utils/typed_graph.py) for any graph-based GNN components.

These conventions ensure new code integrates cleanly with the existing **JAX/Haiku** pipeline without disrupting the autodifferentiation or distributed training paths.

## Run the Test Suite Locally

WeatherNext includes extensive unit tests under `weathernext/utils/`. Validate your changes before submitting:

```bash
pytest weathernext/utils/xarray_tree_test.py

```

All tests must pass before a pull request can be accepted. The CI pipeline enforces this, but running tests locally catches errors faster and demonstrates due diligence to reviewers.

For core architecture changes, also run:

```bash
pytest weathernext/weathernext2/architecture_test.py

```

## Submit and Iterate on Your Pull Request

Open your PR via GitHub's standard interface. The WeatherNext review process checks for:

- **CLA acknowledgment** — Automatically verified via GitHub integration
- **Community guideline conformance** — Documented in [`CONTRIBUTING.md`](https://github.com/google-deepmind/weathernext/blob/main/CONTRIBUTING.md) (lines 22-26)
- **Code quality, documentation, and test coverage**

Address all reviewer feedback promptly. Once approved, a maintainer will merge your contribution.

## Practical Example: Adding a New Data Modality

Below is a complete workflow for extending WeatherNext with a **soil moisture** modality.

First, extend the data structure in [`weathernext/utils/data_modalities.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/data_modalities.py):

```python
from weathernext.utils import data_modalities as dm

class ExtendedCombinedArrays(dm.CombinedArrays):
    """Add a new soil-moisture field."""
    soil_moisture: xr.DataArray

```

Then inject the modality into the forward pass in [`weathernext/weathernext2/architecture.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture.py):

```python
from weathernext.utils import update_blocks as ub

class ForwardPass(...):
    def __init__(self, *, latent_dense_kwargs, ..., mesh_model_ctor, **kw):
        super().__init__(...)
        # Register the new modality with the points-to-mesh constructor

        self._points_to_mesh_model_ctor = {
            "soil_moisture": ub.PointsMeshUpdateConstructor(custom_soil_encoder),
            None: ub.PointsMeshUpdateConstructor(default_encoder),
        }

```

Validate the implementation:

```bash
pytest weathernext/weathernext2/architecture_test.py

```

## Key Files for Contributors

- [`CONTRIBUTING.md`](https://github.com/google-deepmind/weathernext/blob/main/CONTRIBUTING.md) — CLA requirements, review process, and community guidelines
- [`weathernext/weathernext2/architecture.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture.py) — Core forward-pass implementation for WeatherNext 2 (FGN)
- [`weathernext/weathernext2/architecture_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture_utils.py) — Input classification, merging, and dtype helpers
- `weathernext/utils/` — Shared utilities for graph building, normalization, and rollouts
- [`weathernext/utils/xarray_tree_test.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/xarray_tree_test.py) — Unit tests for xarray utilities

## Summary

- **Sign the Google CLA** before any contribution—this is a hard requirement
- **Fork and branch** with focused, atomic changes
- **Follow architecture patterns** in [`architecture.py`](https://github.com/google-deepmind/weathernext/blob/main/architecture.py) and [`architecture_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/architecture_utils.py)
- **Run local tests** with `pytest` before submitting
- **Iterate on PR feedback** until maintainer approval

## Frequently Asked Questions

### What license covers WeatherNext contributions?

All code contributions are released under **Apache 2.0**. Documentation and other non-code content use CC-BY 4.0. The [`CONTRIBUTING.md`](https://github.com/google-deepmind/weathernext/blob/main/CONTRIBUTING.md) file documents this licensing structure, and your CLA signature acknowledges these terms.

### Can I contribute without signing the Google CLA?

No. The CLA is mandatory for all contributions to WeatherNext. GitHub automatically checks CLA status on every pull request, and the repository's [`CONTRIBUTING.md`](https://github.com/google-deepmind/weathernext/blob/main/CONTRIBUTING.md) explicitly states that no code will be merged without a signed agreement.

### What testing is required before submitting a pull request?

You must run the relevant unit tests locally using `pytest`. For architecture changes, run `pytest weathernext/weathernext2/architecture_test.py`. For utility changes, target the specific test file—such as [`weathernext/utils/xarray_tree_test.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/xarray_tree_test.py). All tests must pass in CI before merge.

### How does WeatherNext handle new data modalities?

New modalities extend `CombinedArrays` in [`data_modalities.py`](https://github.com/google-deepmind/weathernext/blob/main/data_modalities.py) and register encoders via `PointsMeshUpdateConstructor` in the forward pass. The `classify_input_data` and `merge_global_data` utilities in [`architecture_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/architecture_utils.py) handle routing and merging with existing data streams.