cantera/CONTRIBUTING.md

Contributing to Cantera

As an open source project, Cantera relies on contributions from its users. We welcome your participation in the project in any capacity that you are able to contribute, whether that be through writing code, updating documentation, submitting bug reports, or answering questions on the Users' Group. The following guidelines are intended to provide a starting point for contributing code to Cantera.

• If you have an idea for significant change you'd like to implement, please create an issue on the Cantera/enhancements repository on GitHub or start a discussion on the Cantera Users' Group to plan your modifications so that they can be implemented efficiently and in a way that doesn't conflict with any other planned future development
• If you are interested in contributing but don't have a particular goal in mind, there are a few ways to get started:
  • Look over the Enhancements that are listed as "feature requests"
  • Look over the list of open Issues
  • Reach out to the core developers to discuss areas where you could contribute effectively
• When making changes, write code that is consistent with the surrounding code (see the Cantera style guidelines)
• Add tests for any new features that you are implementing to either the GoogleTest-based test suite or the Python test suite. See Writing Tests for more information.
• Add examples that highlight new capabilities, or update existing examples to make use of new features.
• Cantera is licensed under a BSD license which allows others to freely modify the code, and if your changes are accepted, then that code will be release under this license as well. The copyright for Cantera is held collectively by the contributors.
• You can find additional information about how Cantera is structured and tips for developing and debugging Cantera in the Develop section of the Cantera website.
• Keep the eventual code review process in mind while you work. This article on The (written) unwritten guide to pull requests provides some good suggestions on how to prepare your contribution in a way that makes it efficient to review.

Getting Credit for your Contributions

• Configure Git with your name and e-mail address before making any commits
  • From a terminal, run:

    git config --global user.name "Your Name"
    git config --global user.email "you@somewhere.org"
    

  • Make sure the e-mail you specify is linked to your GitHub account. You can view these settings on GitHub by clicking on your profile image in the upper right corner and selecting "Settings". Then, select the "Emails" section from the list on the left of the page.
• If you have made a significant contribution (more than just fixing a typo), please add your name, GitHub handle, and institutional affiliation (if desired) to the AUTHORS file as part of your pull request.
• Do not add any author acknowledgements to individual files.

Git Workflow

• Fork the Cantera/cantera repository on Github
• Clone your new repository or add it as a remote to an existing repository
• Check out the existing main branch, then start a new feature branch for your work.
  • Starting from the latest commit on the main branch, which is always the current development version, will minimize the likelihood of conflicts when merging your pull request.
  • Do not make commits directly to your main branch, or open a pull request from your main branch.
• As you make changes, commit them to your feature branch
  • Use descriptive commit messages (summary line of no more than 72 characters, followed by a blank line and a more detailed summary, if any)
  • Make related changes in a single commit, and unrelated changes in separate commits
  • Make sure that your commits do not include any undesired files, such as files produced as part of the build process or other temporary files.
  • Organize your commits and squash small "fixup" commits and reversions using Git's history-rewriting features such as git rebase -i; see https://help.github.com/articles/about-git-rebase/
  • Do not merge your branch with main. If your branch gets behind Cantera's main branch, you should rebase your branch onto the most recent HEAD commit of main. This allows us to keep a simple, linear project history.
  • Periodically run the test suite (scons test) to make sure that your changes are not causing any test failures.
• Push the changes on your new feature branch to your forked copy of the Cantera/cantera repository on GitHub.
• Submit a Pull Request on Github, from your forked copy. Check the results of the continuous-integration tests run using GitHub Actions and resolve any issues that arise.
• When responding to review comments on your pull request, please do not use the "accept suggestion" option, as this creates a very noisy version history.

The following pages describe the Git development workflows for some other projects. You may also find some helpful advice from these projects:

• Matplotlib
• SciPy