Developer Docs (if you’re going to contribute code)#

As an open source project, the OpenMDAO repository is hosted on GitHub.com, which is your gateway to interacting with and contributing to the project.

Issues and POEMs#

The first step in contributing to OpenMDAO is to identify a feature or behavior that is not working as desired or could be improved. The way to bring this to the attention of the development team is by submitting an issue on GitHub. Here you will specify whether you think you have found a bug, are asking for a change in functionality or have an idea for a completely new feature.

If the change being proposed is large or impacts the user interface, then you should go through the POEM process. A POEM is a “Proposal for OpenMDAO Enhancement”. The POEM process is a mechanism to ensure that significant changes to OpenMDAO are communicated to and vetted by the community before being incorporated.

Developer Install#

In order to contribute code to OpenMDAO, you will first need to fork the OpenMDAO repository on GitHub. This is because contributions must be in the form of a pull request.

Once you have your own fork, you can use git to clone the repository on your PC or development platform of choice:

git clone http://github.com/your_name/OpenMDAO

Then use pip to install openmdao locally:

cd OpenMDAO

pip install -e .

Note

The -e option tells pip to install directly from your repository. This is very useful when you’re developing because when you change the code or pull new commits down from GitHub, you don’t necessarily need to re-run the pip install.

Your changes should be committed (preferably on a branch) and pushed up to your fork, from which you can then submit a pull request.

Signing and Verifying GitHub Commits#

To ensure that they come from a trusted source, only pull requests that consist of verified commits can be merged to the OpenMDAO master branch.

Testing#

Any new features, bug fixes or other changes to the code base must be accompanied by one or more tests to verify that the change has the intended functionality. In addition, the existing test suite must be run to verify that there are no regressions or unintended consequences.

Linting#

In addition to having tests that check for code and documentation formatting issues, the OpenMDAO project is configured to enable automatic linting when you do a git commit via a pre-commit hook. Since continuous integration testing will also do this same linting check with the ruff linter, it can save time to catch these issues before before pushing your changes up to GitHub.

To enable automatic ruff linting, make sure you have installed the [test] dependencies and then issue the pre-commit install command in your development environment. After doing this, the pre-commit hook will automatically run a ruff check whenever you make a commit. The hook can also be run manually on changed files using pre-commit run or on all files via pre-commit run --all. You can also add your own pre-commit hooks. See the documentation here.

Building the Docs#

You can read the docs online, so it is not necessary to build them locally on your machine. But if you’re going to build new features or add new examples, you’ll want to build the docs locally, so that you can check them while you are writing them.

Creating Your Own OpenMDAO Plugins#

Documentation Style Guide#

This document exists to help OpenMDAO documentation writers follow appropriate guidelines, in terms of formatting and embedding code.