# Contributing to MechJeb

MechJeb is a long-running, complex codebase covering guidance, trajectory optimization, and orbital mechanics. Contributions are welcome, but the standards are high and the review economics are tight. This document exists so that prospective contributors understand what to expect before investing significant effort.

## Before You Write Code

For anything beyond small bug fixes or documentation changes, open an issue first and describe what you want to do. New guidance algorithms, new modules, and significant changes to existing subsystems require a design discussion *before* code is written. This is not bureaucracy — it is the cheapest way to discover whether your idea fits the project's direction, whether someone is already working on something similar, and what shape an acceptable implementation would take.

A large PR that lands without prior discussion is much more likely to be rejected outright, regardless of how much work went into it. Save yourself the trouble and start with an issue.

## A Note on AI-Assisted Contributions

Everyone is now armed with AI coding agents, and the maintainers of this project use them too. This changes the economics of contribution in ways that contributors need to understand.

Code is now cheap to produce. Review is not. The limiting factor on this project is the attention of the humans who maintain it. Generating large volumes of agentic code is easy; reviewing it, understanding it, integrating it, and maintaining it for years afterward is not — and that cost falls on the maintainers, not on the person who submitted the PR. A 2,000-line PR generated by an agent in an afternoon can easily represent weeks of maintainer time to properly evaluate, and orders of magnitude more if it lands and needs to be debugged later.

Because of this, the bar for AI-assisted contributions is not lower than for hand-written ones — if anything it is higher. In particular:

- The human submitting the PR is expected to have read and understood the relevant parts of the existing codebase. "I had an agent translate a paper into C#" is not a contribution; it is a starting point at best.
- The human submitting the PR is expected to be the one making the design decisions, not delegating them to the agent. Why is the algorithm structured this way? Why this numerical method and not another? Why does it integrate with the existing code in this particular way? You should be able to answer these questions in detail.
- Submissions that are not well anchored in the existing codebase will generally be rejected. Signs of this include reimplementing utilities that already exist elsewhere in the code, forking existing APIs rather than extending them, using conventions that don't match the surrounding code, and being unable to explain why your code looks the way it does.

If you would not be able to maintain the code you are submitting without further AI assistance, neither will we, and that is a strong reason not to merge it.

## Duplication

Contributors are expected to integrate with existing code, not work around it. If an existing API is wrong or insufficient for your use case, the correct response is to propose changing it — in an issue, before writing code — not to introduce a parallel implementation.

Duplicate math utilities, duplicate helper functions, and parallel implementations of things that already exist will be rejected. If you find yourself reimplementing something that already exists in the codebase, stop and figure out why. Either the existing implementation should be extended to handle your case, or your approach is wrong and the friction is telling you so. The instinct to fork rather than touch existing APIs is understandable — it feels polite — but in practice it shifts the cleanup cost onto the maintainers, and over multiple contributors it produces a codebase with five half-overlapping implementations of every utility and no clear canonical version of anything.

## Long-Term Maintenance

Contributing a major subsystem is a multi-year commitment, not a one-time event. We expect contributors of significant new code to remain available to fix issues, respond to bug reports, and follow up on regressions in code they have written. Drive-by contributions of large new modules will be viewed with skepticism for exactly this reason — if you are not going to maintain it, the maintainers will, and that is a cost factored into whether to accept the PR in the first place.

If you are not in this for the long term, please contribute something small instead. There is plenty of room to be useful without signing the project up for an obligation you do not intend to honor.
