|
| 1 | +# Contributing to Michelangelo |
| 2 | + |
| 3 | +Michelangelo welcomes contributions from the community. This guide is your entry point — it explains what you can contribute, where each part of the codebase lives, and how to get started. |
| 4 | + |
| 5 | +## Types of Contributions |
| 6 | + |
| 7 | +| Type | Examples | |
| 8 | +|------|---------| |
| 9 | +| New Uniflow plugins | Add a Flink task type, a new compute backend | |
| 10 | +| API extensions | New proto resource, new controller | |
| 11 | +| Bug fixes | Scheduler edge cases, controller reconcile bugs | |
| 12 | +| Documentation | Guides, examples, terminology | |
| 13 | +| UI improvements | New pages, component library additions | |
| 14 | +| Testing | Integration tests, test coverage gaps | |
| 15 | + |
| 16 | +For small fixes (typos, obvious bugs), open a PR directly. For new features or significant changes, open a GitHub issue first to discuss the approach before writing code. |
| 17 | + |
| 18 | +## Component Map |
| 19 | + |
| 20 | +Understanding which directory owns which subsystem helps you find the right code quickly. |
| 21 | + |
| 22 | +| Area | Directory | Language | |
| 23 | +|------|-----------|----------| |
| 24 | +| API definitions (Protobuf) | `proto/` | Proto | |
| 25 | +| Generated Go protobuf bindings | `proto-go/` | Go (generated) | |
| 26 | +| API server | `go/cmd/apiserver/` | Go | |
| 27 | +| Controller manager | `go/cmd/controllermgr/` | Go | |
| 28 | +| Workflow worker | `go/cmd/worker/` | Go | |
| 29 | +| Uniflow plugins (Go layer) | `go/worker/plugins/` | Go | |
| 30 | +| Shared controller components | `go/components/` | Go | |
| 31 | +| Python SDK (Uniflow) | `python/michelangelo/uniflow/` | Python | |
| 32 | +| CLI (`ma`) | `python/michelangelo/` | Python | |
| 33 | +| Web UI | `javascript/` | TypeScript/React | |
| 34 | +| Bazel build configuration | `BUILD.bazel`, `MODULE.bazel`, `WORKSPACE.bazel` | Bazel/Starlark | |
| 35 | + |
| 36 | +**API server** (`go/cmd/apiserver/`) is a gRPC server that acts as the control plane API. It validates and stores resources (CRDs via the Kubernetes API), and invokes registered API hooks. |
| 37 | + |
| 38 | +**Controller manager** (`go/cmd/controllermgr/`) runs Kubernetes controllers for each ML resource type (RayCluster, SparkJob, InferenceServer, Deployment, Pipeline, etc.). Each controller reconciles the desired state in etcd with the actual state in compute clusters. |
| 39 | + |
| 40 | +**Worker** (`go/cmd/worker/`, `go/worker/plugins/`) hosts Temporal/Cadence workflow and activity workers. Uniflow plugins extend the worker with domain-specific capabilities (Ray cluster management, Spark job submission, etc.). |
| 41 | + |
| 42 | +**Uniflow SDK** (`python/michelangelo/uniflow/`) is the Python framework users write workflows in. It provides `@uniflow.task()` and `@uniflow.workflow()` decorators. At submission time, Python workflows are transpiled to Starlark and executed by the worker. |
| 43 | + |
| 44 | +## Before You Start |
| 45 | + |
| 46 | +1. **Fork and clone** the repository |
| 47 | +2. **Read [TERMINOLOGY.md](TERMINOLOGY.md)** — understand the vocabulary (Task, Workflow, Pipeline, PipelineRun, etc.) before reading code |
| 48 | +3. **Build from source** — follow [Building from Source](building-michelangelo-ai-from-source.md) to ensure your environment is working |
| 49 | +4. **Set up the sandbox** — `poetry run ma sandbox create` gives you a local Kubernetes cluster with all Michelangelo components running. Most integration tests and manual testing use this. |
| 50 | + |
| 51 | +## Finding Work |
| 52 | + |
| 53 | +- Browse [GitHub Issues](https://github.com/michelangelo-ai/michelangelo/issues) filtered by `good first issue` or `help wanted` |
| 54 | +- Issues are tagged by component (e.g., `area/serving`, `area/jobs`, `area/uniflow`) to help you find relevant work |
| 55 | +- If you have an idea that isn't tracked yet, open an issue before writing code |
| 56 | + |
| 57 | +## Making a Contribution |
| 58 | + |
| 59 | +1. Create a branch from `main`: `git checkout -b feat/your-feature` |
| 60 | +2. Make your changes following the relevant guide below |
| 61 | +3. Write tests (see [Testing Strategy](testing.md)) |
| 62 | +4. Run linters locally before pushing |
| 63 | +5. Push and open a PR — see [PR Process](pr-process.md) |
| 64 | + |
| 65 | +## Contribution Guides by Type |
| 66 | + |
| 67 | +### New Uniflow plugin |
| 68 | +The most common contribution type. Uniflow plugins add new task execution environments (new compute backends, external services, etc.). |
| 69 | + |
| 70 | +→ **[Uniflow Plugin Guide](uniflow-plugin-guide.md)** — end-to-end walkthrough (Go worker plugin → Starlark orchestration → Python `TaskConfig`) |
| 71 | + |
| 72 | +### New API resource (proto + controller) |
| 73 | +Adding a new ML resource type requires proto definitions, a gRPC service, and a Kubernetes controller. |
| 74 | + |
| 75 | +→ **[How to Write APIs](how-to-write-apis.md)** — proto definitions, Gazelle, gRPC code generation |
| 76 | + |
| 77 | +### Go backend changes |
| 78 | +For changes to the API server, controller manager, worker, or shared components. |
| 79 | + |
| 80 | +→ **[Error Handling](dev/go/error-handling.md)** — required patterns for controllers and services |
| 81 | +→ **[Managing Go Dependencies](manage-go-dependencies.md)** — `go mod tidy` + `bazel mod tidy` |
| 82 | +→ **[Using Go Mocks in Tests](use-go-mocks-in-unit-test.md)** — gomock patterns |
| 83 | + |
| 84 | +### Python SDK changes |
| 85 | +For changes to the Uniflow decorators, task types, or the `ma` CLI. |
| 86 | + |
| 87 | +→ **[Python Coding Guidelines](dev/python/mactl/coding_guidelines.md)** |
| 88 | + |
| 89 | +### UI changes |
| 90 | +For changes to the Michelangelo web UI. |
| 91 | + |
| 92 | +→ **[UI Development](dev/ui/index.md)** — component patterns, types, configuration system |
| 93 | + |
| 94 | +### Documentation |
| 95 | +For adding or improving guides, references, or examples. |
| 96 | + |
| 97 | +→ **[Documentation Guide](documentation-guide.md)** — formatting, structure, and style conventions |
| 98 | + |
| 99 | +## Getting Help |
| 100 | + |
| 101 | +- **GitHub Issues** — for bug reports and feature requests |
| 102 | +- **GitHub Discussions** — for questions about the codebase, design discussions, and community Q&A |
0 commit comments