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 Cantera authors file AUTHORS.md 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:

Restrictions on Generative AI Usage#

We expect authentic engagement in our community.

  • Please be considerate posting content generated by AI models. Make sure that the content is valuable, concise, and expresses the message you want to share.

  • If you use generative AI tools as an aid in developing code or documentation changes, you are required to disclose the use of AI and ensure that you fully understand the proposed changes and can explain why they are the correct approach.

Make sure you have added value based on your personal competency to your contributions. Just taking some input, feeding it to an AI and posting the result is not of value to the project. To preserve core developer capacity, we reserve the right to reject low-value contributions. (adapted from Matplotlib’s AI Usage guidelines)

Disclosures and Authorship#

Cantera is distributed under a BSD-3-Clause license with contributions from California Institute of Technology, Sandia Corporation (with U.S. Government rights), and the Cantera Developers. Because this license requires clear attribution and provenance, contributors must follow the rules below when using generative AI tools.

1. AI Use Disclosure#

All pull requests must include a brief AI Use Statement in the PR description. Please start with the appropriate category below, and in the latter cases, adjust the description to describe how generative AI was used in this specific PR.

  • No generative AI was used. This contribution was written entirely without AI assistance.

  • Limited use of generative AI. Standard or boilerplate code snippets were generated with AI and manually reviewed; all design, logic, and implementation decisions were made by the contributor. Examples: IDE code-completions or brief LLM queries for common patterns.

  • Extensive use of generative AI. Significant portions of code or documentation were generated with AI, including logic and implementation decisions. All generated code and documentation were reviewed and understood by the contributor. Examples: Output from agentic coding tools and/or substantial refactoring by LLMs (web-based or local).

How to choose:

  • Limited: AI helped with syntax, boilerplate, or standard patterns; you designed the solution.

  • Extensive: AI suggested the approach, algorithm, or structure; you validated it works.

2. Authorship and Licensing Requirements#

Contributors must ensure that:

  • They have the rights to license their contribution under the project’s BSD-3-Clause terms.

  • They do not knowingly submit AI-generated content derived from copyrighted or license-incompatible sources (examples: GPL code, proprietary libraries).

  • All required attribution and copyright notices for contributed material are preserved as required under BSD-3-Clause.

As generative AI systems may emit material similar to third-party codebases, contributors must exercise caution. Contributors should exercise reasonable care in:

  • verifying that AI suggestions are sufficiently original,

  • avoiding verbatim snippets with incompatible licenses, and

  • ensuring that any third-party content incorporated intentionally follows proper attribution and is license-compatible.

3. Maintainer Review and Discretion#

Maintainers may:

  • request clarification about the origin of AI-assisted code,

  • ask the contributor to manually rewrite suspect portions, or

  • reject contributions where provenance is unclear or license compatibility cannot be reasonably established.

These measures protect the integrity of the project’s licensing and long-term maintainability.

On this page
Show Source