How to Contribute to MACH-Aero

The codes in the MACH-Aero framework are open-source tools, so we welcome users to submit additions or fixes to improve them for everyone. This page contains general information on how to contribute to MACH-Aero codes. If a repo has additional instructions they will be in that repo’s documentation, which can be found from its GitHub page.

Issues

If you have an issue, a bug to report, or a feature to request, submit an issue on the GitHub repository for that specific code. This lets other users know about the issue. If you are comfortable fixing the issue, please do so and submit a pull request from a branch on your own fork of that repo.

Coding style

We use formatters specific to different programming languages to increase readability and standardization of code. We run continuous integration with these tools on all pull requests submitted. For an easier workflow, we recommend integrating these tools with your code editor.

Python

We use ruff and pre-commit for linting and formatting our Python codes. Only pre-commit is required to run these checks locally:

pip install pre-commit

If you want to run ruff as a standalone tool, you can install it with:

pip install ruff==0.12.10

To match the checks we run in our CI pipelines, you will need to download our configuration files. Download our pre-commit configuration file from here and place it in the root of the respective repository, or place it somewhere central (e.g $HOME/.config/pre-commit) and soft-link to it in the repository:

mkdir -p $HOME/.config/pre-commit
cd $HOME/.config/pre-commit
wget https://raw.githubusercontent.com/mdolab/.github/main/.pre-commit-config.yaml
cd <path to the root of the repo>
ln -s $HOME/.config/pre-commit/.pre-commit-config.yaml .pre-commit-config.yaml

Follow a similar process for the ruff configuration file, which can be found here. There are a few options for where to place this file. The preferred option is save the file to $HOME/.config/ruff/ruff.toml.

mkdir -p $HOME/.config/ruff
cd $HOME/.config/ruff
wget https://raw.githubusercontent.com/mdolab/.github/main/ruff.toml

If you already have a global ruff configuration file in this location that you want to keep, you can also save our config file in one of the following locations that ruff will automatically find

The root of the repository you’re working on.
The parent directory of the repository you’re working on.

Note

Some of our repositories already have a local ruff.toml config file in their root. These local config files are setup to automatically extend the global config file stored at $HOME/.config/ruff/ruff.toml. If you have chosen to save our global ruff.toml file in a different location, you will need to edit the extend field in the local config file to point to the correct location of your global config file.

Once the config files are in place, you can run the pre-commit and ruff checks with:

pre-commit run --all-files

Pre-commit and ruff will fix all automatically fixable issues and print out any remaining ones that need to be fixed manually. To have these pre-commit checks run automatically on every commit, run:

pre-commit install

Fortran

We use fprettify for formatting Fortran codes. The version we use can be installed with:

pip install fprettify==0.3.7

The configuration file for fprettify is at the root of the respective repository. If there isn’t a repo-specific config, this global fprettify config is used. fprettify can then be run at the project root using this fprettify bash script with:

./fprettify.sh

C/C++

We use clang-format to format C/C++ codes. Please install version 10 following its documentation.

The configuration file for clang-format is at the root of the respective repository. If there isn’t a repo-specific config, this global clang-format config is used. clang-format can then be run at the project root using this clang-format bash script with:

./clang-format.sh

Warning

For a PR to be accepted it must pass formatting checks with the relevant formatter and/or linter.

Documentation

When you add or modify code, make sure to provide relevant documentation that explains the new code. This should be done in code via docstrings and comments as well as in the Sphinx documentation if you add a new feature or capability. Look at the .rst files in the doc section of each repo.

Building the documentation requires our custom Sphinx theme. To install the MDO Lab theme and its dependencies, type:

pip install sphinx-mdolab-theme

To build documentation locally, go to the doc folder and type:

make html

The HTML files are then generated in _build/html and can be viewed in a web browser.

Testing

When you add code or functionality, add tests that cover the new or modified code. These may be units tests for individual components or regression tests for entire models that use the new functionality. All the existing tests can be found under the tests folder. Running tests requires additional packages in some repos. To install these, go to the root of that repo and type:

pip install .[testing]

We use Codecov to monitor the percentage of the code covered by tests. Coverage can be difficult to determine locally, so it is recommended to look for the check automatically run in the pull request.

Warning

For a PR to be accepted, all existing tests must pass and new code should meet coverage requirements.

Pull requests

Finally, after adding or modifying code and making sure the steps above are followed, submit a pull request via the GitHub interface. This will automatically go through every test in the repo to make sure everything is functioning properly as well as check the formatting and the code coverage. The main developers of the respective repo will then merge in the request or provide feedback on how to improve the contribution.