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

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 to view or sign your agreement. The repository's 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:

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, with helper utilities in 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 (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).

• Typed-graph construction — Follow the patterns in 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:

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:

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 (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:

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:

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:

pytest weathernext/weathernext2/architecture_test.py

Key Files for Contributors

• CONTRIBUTING.md — CLA requirements, review process, and community guidelines
• weathernext/weathernext2/architecture.py — Core forward-pass implementation for WeatherNext 2 (FGN)
• 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 — 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 and 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 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 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. All tests must pass in CI before merge.

How does WeatherNext handle new data modalities?

New modalities extend CombinedArrays in 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 handle routing and merging with existing data streams.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}