Skip to content

Contributing

Jump to bottom
Joshua Shinavier edited this page Jun 5, 2026 · 1 revision

Contributing

This page is the contributor guide for Hydra. It describes how to get oriented, choose the right workflow, and submit changes that fit the project.

Hydra is preparing for 1.0 and possible Apache Incubator entry, so contributions are most useful when they improve correctness, portability, documentation, release discipline, or the developer experience.

Start here

If you want to use Hydra as a library, start with Getting started.

If you want to change Hydra itself, start with Contributor setup. Hydra spans several host languages, and the setup guide groups prerequisites into tiers:

  • Kernel — Haskell host only.
  • Triad — Haskell, Java, and Python; the routine cross-host validation path.
  • Full matrix — Triad plus Scala and the Lisp dialects.
  • Go bud and Authoring — optional add-ons for Go work and GitHub/release tooling.

You do not need the full matrix for every contribution. Pick the smallest tier that covers the work you plan to do.

Documentation map

  • Implementation guide explains the kernel, DSL sources, primitives, coders, and bootstrap process.
  • Build system explains sync phases, generated artifacts, cache behavior, and distribution assembly.
  • Developer recipes give task-oriented instructions for adding primitives, extending core types, refactoring modules, running benchmarks, and maintaining the repo.
  • Coding style is required reading before changing Hydra source code.
  • Troubleshooting covers common failures across builds, syncs, and tests.

The wiki is for settled design, rationale, and project policy. The docs/ tree is for contributor workflows and implementation details.

Repository layout

Hydra separates source descriptions, host runtimes, runtime overlays, bindings, and generated output:

  • packages/ holds DSL source packages.
  • heads/ holds host runtimes, generators, tests, and build descriptors.
  • overlay/ holds hand-written runtime source copied into generated distribution packages.
  • bindings/ holds host-specific integrations with external systems.
  • dist/ holds generated and copied artifacts.

See Code organization for the full model.

Development expectations

Hydra is strongly typed and fail-loud by design. Contributions should preserve that discipline:

  • Do not silently swallow errors or return defaults for failed computations.
  • Keep definitions and corresponding implementation bodies in alphabetical order where the coding style requires it.
  • Keep generated output generated. Do not edit files under dist/ by hand except for an explicitly planned bootstrap patch that will be overwritten by regeneration.
  • If generated code is wrong, fix the generator or source DSL, not the generated file.
  • Use existing module patterns, import conventions, and helper APIs before introducing new abstractions.
  • Keep documentation changes aligned with the documentation style guide.

Build and test

For kernel work, run the Haskell tests from heads/haskell:

cd heads/haskell
stack test

For the default Haskell / Java / Python path, use:

./bin/sync-default.sh
./bin/test.sh

For broader changes, use the relevant sync or test scope described in the build-system guide and developer recipes. Do not proceed past failing tests; investigate and fix the failure first.

Pull requests

Prefer small, focused pull requests. Each pull request should explain:

  • what changed
  • why it changed
  • how it was tested
  • whether generated artifacts were regenerated
  • any follow-up work or known limitations

For documentation changes, include the audience and purpose of the change. For source changes, include the validation commands you ran.

AI-assisted contributions

Hydra uses AI-assisted development, but AI assistance does not reduce the review bar. Contributors are responsible for understanding, testing, and reviewing every change they submit.

AI-assisted changes should:

  • be reviewed by a human contributor before merge
  • avoid copying incompatible licensed material
  • cite external sources when documentation relies on them
  • follow the same generated-file, testing, and style rules as any other change

See LLM-assisted development for project-specific guidance.

Community and governance

Hydra is moving toward a more explicit contributor and governance model as part of the Apache Incubator readiness work tracked by #441.

This page is the contribution baseline. Future governance documentation should add decision-making, maintainer expectations, release-manager roles, and the contributor-to-committer path.

Clone this wiki locally