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 black for formatting Python codes. The version we use can be installed with:

pip install black==23.1.0

black can then be run at the project root with:

black . -l 120

This will automatically format all Python files.

We use flake8 for linting in Python. The recommended version and any necessary dependencies are in this file. You can install them by calling pip install for each individually or copying the contents of that file into one on your machine and typing:

pip install -r flake8-requirements.txt

The configuration file we use for flake8 is a combination of this .flake8 file and the one at the root of the respective repository. flake8 can then be run at the project root with:

flake8 .

If there are any PEP-8 violations, flake8 will print out the nature of the violation.

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.