.. _contribute: 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: .. prompt:: bash pip install pre-commit If you want to run ruff as a standalone tool, you can install it with: .. prompt:: bash 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: .. prompt:: bash mkdir -p $HOME/.config/pre-commit cd $HOME/.config/pre-commit wget https://raw.githubusercontent.com/mdolab/.github/main/.pre-commit-config.yaml cd 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``. .. prompt:: bash 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 1. The root of the repository you're working on. 2. 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: .. prompt:: bash 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: .. prompt:: bash pre-commit install Fortran ^^^^^^^ We use `fprettify `_ for formatting Fortran codes. The version we use can be installed with: .. prompt:: bash 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: .. prompt:: bash ./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: .. prompt:: bash ./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: .. prompt:: bash pip install sphinx-mdolab-theme To build documentation locally, go to the ``doc`` folder and type: .. prompt:: bash 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: .. prompt:: bash 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.