Skip to content

Forking Policy

When Marin needs a modified version of an upstream package, we maintain a fork under the marin-community GitHub organization rather than vendoring code into the Marin monorepo. This page documents the requirements for creating and maintaining such forks.

Requirements

  1. Host the fork in marin-community/<package>. Do not pull the forked source tree into the Marin repo. Keep it as a standalone repository under the organization (e.g. marin-community/harbor, marin-community/vllm-tpu).

  2. Set up CI to autobuild wheels on push to main. Every push to the fork's main branch must produce a versioned wheel via GitHub Actions (or equivalent CI). There should be no manual "run this script to get new wheels" step.

  3. Pin by version hash in Marin's pyproject.toml. Marin should depend on the fork via a wheel URL or a git dependency with a pinned revision, so that uv sync runs quickly and results are cacheable. Example from pyproject.toml:

harbor = { git = "https://github.com/marin-community/harbor.git", rev = "354692d..." }

Existing Forks

Package Repository How Marin depends on it
Harbor marin-community/harbor Git dependency pinned to a commit rev in the root pyproject.toml
vllm-tpu marin-community/vllm-tpu PyPI version pin (vllm-tpu==0.19.0) in lib/marin/pyproject.toml

When to Fork

Fork only when:

  • You need patches that upstream has not (or will not) accept.
  • The upstream release cadence is too slow for a fix you need now.
  • You need a custom build (e.g. TPU-specific wheels).

Prefer upstreaming changes when possible. A fork is ongoing maintenance overhead — even with agents helping, keeping it in sync takes effort.

Maintaining a Fork

  • Keep the fork's main branch rebased or merged regularly against upstream.
  • Tag releases that correspond to the pinned revisions in Marin so the provenance is clear.
  • When bumping the pinned revision in Marin, update the rev in pyproject.toml and run uv sync to verify resolution.