Skip to content

Contributing

Dew is small on purpose. Every line has to earn its place. These rules apply to people and to agents alike, and a review checks each one.

  • Compose before you write. Look for the primitive first: jax.nn.dot_product_attention (grouped-query heads, causal and windowed masks, the fused kernels), flax.linen (norms, embeddings, attention with its decode cache, scan, remat), optax (losses, schedules, transforms), orbax (checkpoints and retention), grain (sources, sharding, batching, packing), and Google’s own JAX code (MaxText, tokamax, the gemma library) for anything they already do well. A reimplementation needs a reason a reader can check: a measured inefficiency, a missing feature, or a parameter layout we must match. Write that reason where the code is.
  • One path. A capability has one implementation, one config field, one registry entry. No fallbacks, flags or compatibility layers without a demonstrated need.
  • The seams are the contract. Models are plain Flax modules that know nothing about training. Objectives own parameters, loss and validation. The trainer owns the mesh, the compiled step, EMA, checkpoints and logging. Data sources produce records; transforms are Grain transforms. A new architecture is a module and a registry entry; a new modality is an objective. If a change needs to cross these lines, change the design so that it does not.
  • Consume capabilities. An objective, a task, a server, the trainer or an exporter asks a model what it can do through dew.nn.protocols and calls it through Flax’s apply. It never asks which class the model is or reads the model’s private Flax state; tools/lint_slop.py (SLOP010) rejects both outside the module that defines the class. A model without a capability fails with an error that names the capability. A method whose mathematics a model cannot meet (a causal model as a bidirectional denoiser, MeanFlow without an interval input) refuses it for that reason. The scopes a model owns (its parameter tree, its cache, its collections) stay its own. A source codec maps one family’s weight and config schema, so it dispatches on the source’s config. Registration in dew.registry.models is for persistence, to rebuild a saved run; a live model trains and serves without it. A new family or capability extends tests/test_capability_matrix.py.
  • Prefer deep modules: a small interface over real complexity. Delete an abstraction if inlining it makes the code clearer.
  • The public API is types and their methods. What acts on one of Dew’s types is that type’s method or classmethod (RunConfig.override, Pipeline.map), and a choice among behaviours is a type implementing a protocol (RandomSearch, GridSearch), not a function passed by name. Public module-level functions are array transforms, plain-data codecs, and the canonical data compilation and publication boundaries (load, compile, iterate, validation, export, publish). Anything else is private to its module.
  • Frozen at 1.0: parameter tree names and shapes, the checkpoint layout, wandb metric keys, the Objective methods, and the Hugging Face parameter layout of CausalTransformer. Dew is unpublished, so until 1.0 these change outright, with no converter and no compatibility path, with one exception: a saved run’s record whose shape changes keeps one translation per component, applied only where a saved run’s records are read (dew.config.earlier_run for its run record, dew.inference.tasks.saved_artifact for a step’s declaration, a task’s own sidecar reader), so earlier runs keep loading, and each such translation is deleted at 1.0. From 1.0 on, a change to any of them is a migration, with a converter and a test that loads the old form.

Anything that implements a published architecture, schedule, sampler or loss is a port, and a port is correct only when it reproduces the reference.

  • Match the reference design exactly: the same parameter layout, the same operation order where numerics depend on it (norm placement, RoPE convention, softcapping, attention scaling, the dtype each step runs in), and the same defaults. A rearrangement is allowed only with a test that shows it agrees with the reference.
  • A parity test ships with the port. It loads the same weights into Dew and into the reference (the transformers implementation for model families, the authors’ code for a paper, the equation for a schedule), runs the same inputs, and holds Dew’s outputs and gradients to the reference through the accuracy gate, which tests/reference_error.py owns and states (Numerical accuracy).
  • Fixtures are reproducible. The script that generates reference outputs is committed under tools/, the fixtures it produced are small and committed under tests/fixtures/, and a network-marked test regenerates them against the real checkpoint when it is available. A fixture that nobody can regenerate does not count as evidence.
  • Configuration round-trips. A reference config.json translates into Dew’s fields and back without loss; the translation is tested on the real configs of the smallest checkpoint of each family.
  • Keep the smallest correct implementation. Remove dead parameters and unreachable branches. Keep a helper when it owns a coherent operation or hides meaningful complexity, even with one caller.
  • Fix the cause, by design, where it lives: in the shared piece, not in the script or test that hit it, removing the special case or copy that allowed it. Do not suppress warnings, special-case inputs or fill in zeros as a fallback. Derive a fact from its one source instead of passing it in and checking it, order steps so races cannot occur, and add a conditional, timeout or assert only when no design change removes the need; timeouts belong at external boundaries such as networks and cloud allocation. The one exception: once the same computation in float64 shows Dew’s math right, a quirk of XLA’s CPU backend alone is recorded as an open item, not chased.
  • Duplication is banned everywhere, not only in src/: a dependency list, version pin, table, flag set, test list, policy or algorithm exists in one place, and CI workflows, installers, armada recipes and docs read or generate from that one owner. Code composes on itself: one path per job, and as few branches and special cases as the problem allows. When a design grows branches, look at it from another angle (the data, the caller, the hardware, the math).
  • No hidden side effects. Importing a module changes nothing outside it: no monkeypatching of other modules, no global config or environment writes, no I/O. The one exception is the process’s JAX and XLA setup, which lives in one documented place.
  • Put optimizations in the shared core so every model family and backend benefits. Keep model- or hardware-specific code small and say why it cannot be general.
  • Types are narrow and true. No Any, and no casts to quiet a checker. dew ships py.typed, so a caller’s checker reads these annotations, and a wrong one misleads every caller. tools/check.sh’s pyright gate owns the type check, run from the repository root, where pyproject.toml names the environment. A worktree has no .venv of its own, so pyright run there resolves no imports and reports hundreds of errors in clean files. From a worktree, pass the interpreter instead: PYTHON=../../.venv/bin/python sh tools/check.sh. When the untrue type belongs to a dependency without py.typed, narrow it with a stub under stubs/ (the stubPath that pyproject.toml names) and say which signature the stub declares. CI runs pyright on the Python .python-version names with --pythonpath set to its own interpreter, and fails on an error.
  • The venv installs dew editable, so import dew from the repository root reads src/. A worktree is not the root: run its tests through pytest, whose pythonpath puts the worktree’s src/ first, and its scripts with PYTHONPATH=src, or they read the main checkout’s source and report on the wrong tree.
  • Comments say why, never what or what changed. Docstrings describe the code as it is.
  • One lint gate, run from the repository root: sh tools/check.sh. Its gates are the lines of tools/check_gates, run side by side, one per processor, so the check takes about as long as its slowest gate; sh tools/check.sh --gate NAME runs one and --list names them. Ruff’s configuration and pin live in pyproject.toml, where every ignore carries the one-line reason it exists. tools/lint_slop.py is this repository’s own checker for what ruff and a type checker cannot state. Its module docstring names every rule, the roots each rule runs over and the analysis boundaries it does not cross. An ignore in pyproject.toml is only for a third-party style default that is wrong for this code, with its reason next to it, never a # noqa in src/. A rule that enforces one of Dew’s own bans is never ignored: a false finding is fixed in the checker. A new ban lands together with its rule, and tools/lint_slop.py checks every ban a program can check, with no per-finding suppression. The one exception is an import kept for the registry entry it makes, which carries # noqa: F401 (registers the kind).
  • Its fast half, ruff and tools/lint_slop.py, runs before each commit on the staged Python files once the hook is installed. From the repository root, with the environment the gate uses active: printf '#!/bin/sh\nexec sh tools/pre-commit\n' > "$(git rev-parse --git-common-dir)/hooks/pre-commit" && chmod +x "$(git rev-parse --git-common-dir)/hooks/pre-commit". It sits beside Git LFS’s hooks, and every worktree runs its own tools/pre-commit. Pyright and the tests stay in CI.
  • While iterating on a head, sh tools/check.sh --changed runs, in seconds, the gates its own Python files decide: ruff and slop lint over the files that differ from its merge-base with origin/main, committed or not, SLOP020’s ratchet, and the duplicate scan’s structural reading held to origin/main. A shallow checkout first fetches origin/main and its history (tools/base_history.sh). The whole sh tools/check.sh runs before a LAND.
  • Measure performance claims. A change that claims to be faster ships with the number, the command that produced it and the hardware it ran on. Defaults are the fast ones.
  • Performance never costs anything else. Two measures decide an optimization: the accuracy gate, on its loss, gradients and outputs against float64 truth, and its compute time and peak memory. One that passes the gate and removes nothing observable is accepted whatever arithmetic it uses (a reordered sum, a fused or folded form); its arithmetic alone is no reason to reject it. A test that would fail if a term were dropped ships with it.

A test is worth keeping only if it would fail on a plausible bug in the thing it names. Before committing one, ask what change to the code would make it go red; if the answer is “none” or “only deleting the function”, it is not a test.

  • Test observable behavior through public interfaces: numerical results, state transitions, error handling, shapes, dtypes, and sharding where they are part of the contract. A shape-only assertion does not prove numerical correctness; a mock call or self-equal constant does not prove behavior. A refusal is proved by a valid setup that changes one thing and raises, not by the error’s wording, and no test reads the source (tools/lint_slop.py, SLOP011).
  • Test at the seam where the behaviour lives, through the public interface, with real inputs. Mock only at real external boundaries (network, disk, a service). A stub that returns the value the test then checks proves nothing.
  • Prove the test can fail. A bug fix ships with the test that failed before the fix and passes after, both runs shown in the commit or review. A new invariant ships with a mutation that breaks it (drop a term, flip a comparison, skip a chunk) and the assertion that the mutated code fails.
  • Tests are end-to-end runs of real use cases on real model architectures: load or build, train, checkpoint, resume, evaluate, export, reload, generate. Each run asserts every contract its flow touches and covers settings chosen to reach as many code paths as possible. Add a unit test only for logic no scenario reaches cheaply, and delete unit tests the scenarios already cover; testing lists the scenarios. Name a test for the use case it runs. A test that would need its name changed when the implementation changes is testing the implementation.
  • Do not assert prose, source spelling, documentation structure, constant inventories, isolated scalar values or generated API-index snapshots.
  • Follow Numerical accuracy for numerical comparisons, including exact-state comparisons. Add no hand-written tolerance.
  • Use fixed seeds for reproducible draws. Follow testing.md’s rules for CPU interpretation and native behavioral flows on the relevant GPU or TPU. Use small cases for logic and representative device-sized cases for native checks. Keep timing in benchmarks and network access behind its marker.
  • No silent skips. importorskip only for an optional dependency, never for the code under test; a test that skips because a module broke is a broken test.
  • Be adversarial. Test the orders that break things: build a loader after a device exists, resume a run mid-epoch, kill a worker, restore a checkpoint into a different mesh, feed a corpus too small for one batch, feed a split with no boundary. A test suite that only uses the safe order lets these bugs through.
  • Assert the invariant. A stream that should end must end (exactly ceil(N/batch) batches, then stop). Records that should be distinct must be distinct. Splits that should be disjoint must be disjoint. Metrics that should reach the tracker must reach it when the stream ends. State the property and let it fail.
  • Multiprocess and multi-device paths are tested with real processes and real meshes: loading.workers above zero with workers actually running, iterator state through a restart, jax.distributed across spawned processes, loss parity between one process and many at the same seed. A single-process simulation of a mesh is necessary and not sufficient.
  • Investigate warnings at their source. Fix our misuse or the dependency defect; record an unresolved upstream warning with its cause. Do not add a filter or exemption to make a failing check pass.
  • For each supported architecture, exercise a real forward/backward update and its claimed placement.

Plain sentences, short, in the register of someone explaining their own work to a colleague. Tables for comparisons. The README and docs describe what the code does today; a claim without code behind it is a bug.

These constructions are banned in prose, docstrings, comments and commit messages. Machine-written text falls into them, and they make a document sound like nobody wrote it.

  • Colon reveals: a noun phrase, a colon, then a dramatic lowercase reveal, as in “Measured, not adopted: where the room is”, “What it costs, stated: a run cannot”, “One design, three parts:”. Write the plain sentence. Colons are for lists, labels and quotes.
  • Binary contrasts: “This is not X, it is Y”, “The question is not X but Y”, “not just X but Y”. State Y.
  • Throat-clearing and faux insight: “Here’s the thing”, “Let me be clear”, “What most people get wrong”, “the part everyone misses”, “the uncomfortable truth is”.
  • Importance puffery: “marks a pivotal moment”, “plays a vital role”, “underscores”, “highlights”, “showcases”, “stands as a testament”. State the fact.
  • Trailing -ing clauses that pretend to explain: ”…, highlighting the team’s commitment”, ”…, reflecting a broader shift”. Say the consequence or cut it.
  • Negative listing and dramatic fragments: “Not a wrapper. Not a framework. A library.” or “That’s it. That’s the whole thing.”
  • Fake-profound endings and recaps: a closing metaphor or aphorism, or a paragraph that restates the section. End on the last concrete point.
  • Weasel attribution: “experts agree”, “studies show”, “widely regarded as”. Name the source or cut the claim.
  • Words that sell: robust, seamless, leverage, utilize, delve, comprehensive, cutting-edge, elevate, harness, streamline, empower, paramount, intricate, transformative, ever-evolving.
  • Em dashes: do not use them. Commas, periods and parentheses cover every case.
  • Formatting decoration: no emoji in headings, no bold mid-sentence for emphasis, no bullet list where two sentences read better, and no heading over a two-sentence section.
  • Write for a Python/ML reader new to Dew; state any JAX or Flax prerequisite. Teach a complete workflow before advanced options, and separate tutorials, task guides, explanations, and reference.
  • Use public APIs and explain inputs, shapes, dtypes, randomness, state, outputs, and relevant limits. Keep research history and implementation rationale outside the primary learning path.
  • Keep examples self-contained, with imports, inputs, dependencies, and required files. Keep API examples current when behavior changes.
  • Identify download and hardware requirements. Do not claim that an unexercised runtime path works.
  • A tutorial’s diagrams, charts and animations are SVG from dew.figures, never mermaid or matplotlib. A concept figure is drawn in docs/assets/figures.py and embedded in Markdown, alone in its paragraph, by its raw GitHub URL on main, which Colab loads and the site inlines; a figure from the notebook’s run is a cell’s output.
  • The site at dewml.dev is built from docs/, tutorials/ and the docstrings in src/dew; Installation says how to build it. A new docs page goes into site/src/manifest.mjs, a new module that declares __all__ into GROUPS in site/scripts/gen_api.py. The build fails on anything it cannot place.
  • A tutorial uses real models and data on the GPU it needs, and runs once, top to bottom, on that GPU (a Colab or Lambda session). Its install cell pins Dew to the pushed commit it runs on, %pip install "dewml @ git+https://github.com/AshishKumar4/dew@<sha>", and the run installs from that pin. Commit the executed notebook with its outputs, kept small, and accelerator: "GPU" in its metadata. It is not run again when the library changes. A change that alters what an output shows records that output again; a change that only renames an API updates the source and keeps the outputs.
  1. Follow the maintainers’ operating rules, the bible §4, for landing checks and approval. Follow native qualification for target-specific evidence. Mark a CUDA-only test with @pytest.mark.gpu(reason=...). Run the native tier there when performing qualification, not in every development GPU session.
  2. Every new number in docs has its reproduction command, and every port has its parity test.
  3. The review its kind of work gets (the maintainers’ rules, the bible, §4) has read the code itself.