diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b916c9a2e..9528ca258 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,30 +1,40 @@ # Contributing to Cantera -* For significant changes, please start a discussion on the Cantera - Users' Group or create an issue on the [Cantera/enhancements](https://github.com/Cantera/enhancements/issues/new/choose) repository - on GitHub 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 -* 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 +* For significant changes, please create an issue on the + [Cantera/enhancements](https://github.com/Cantera/enhancements/issues/new/choose) + 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 * When making changes, write code that is consistent with the surrounding code (see the [Cantera style guidelines](https://cantera.org/dev/develop/style-guidelines.html)) * Add tests for any new features that you are implementing to either the GoogleTest-based test suite or the Python test suite. -* Add examples that highlight new capabilities, or update existing - examples to make use of new features. +* Add examples that highlight new capabilities, or update existing examples to make use + of new features. +* Cantera is licensed under a [BSD + license](https://github.com/Cantera/cantera/blob/main/License.txt) 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. If you have made a + significant contribution, please add your name to the `AUTHORS` file. +* You can find additional information about how Cantera is structured and tips for + developing and debugging Cantera in the [Develop](https://cantera.org/dev/develop/) + section of the Cantera website. + +## 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 +* Configure Git with your name and e-mail address before making any commits * As you make changes, commit them to your feature branch - * Configure Git with your name and e-mail address before making any commits * 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 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. * Use Git's history-rewriting features (such as `git rebase -i`; see - https://help.github.com/articles/about-git-rebase/) to organize your commits + ) to organize your commits and squash "fixup" commits and reversions. * Do not merge your branch with `main`. If needed, you should rebase your branch onto the most recent `HEAD` commit of `main`. @@ -32,16 +42,10 @@ 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. -* Additional discussion of good Git & Github workflow is provided at - http://matplotlib.org/devel/gitwash/development_workflow.html and - https://docs.scipy.org/doc/numpy-1.15.0/dev/gitwash/development_workflow.html -* Cantera is licensed under a [BSD - license](https://github.com/Cantera/cantera/blob/main/License.txt) which - allows others to freely modify the code, and if your Pull Request is accepted, - then that code will be release under this license as well. The copyright for - Cantera is held collectively by the contributors. If you have made a - significant contribution, please add your name to the `AUTHORS` file. + +Additional discussion of good Git & Github workflow is provided at + and + diff --git a/doc/SConscript b/doc/SConscript index 28c3154e7..79347af55 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -48,16 +48,19 @@ if localenv['sphinx_docs']: "#samples/python") copy_matlab_ex_samples = localenv.RecursiveInstall( "#build/doc/samples/matlab_experimental", "#samples/matlab_experimental") + copy_contrib = localenv.Command("#build/doc/sphinx/develop/CONTRIBUTING.md", + "#CONTRIBUTING.md", + Copy("$TARGET", "$SOURCE")) - sphinxdocs = build(localenv.Command('build/doc/sphinx/html/index.html', + sphinxdocs = build(localenv.Command('#build/doc/html/index.html', 'sphinx/conf.py', build_sphinx)) env.Alias('sphinx', sphinxdocs) - env.Depends(sphinxdocs, copy_sphinx) + env.Depends(sphinxdocs, [copy_sphinx, copy_contrib]) env.Depends(sphinxdocs, [copy_python_samples, copy_matlab_ex_samples]) env.Depends(sphinxdocs, env['python_module']) - # Gather all C++ samples into a single directory so they can be presented a single - # sub-gallery by sphinx-gallery + # Gather all C++ samples into a single directory so they can be presented as a + # single sub-gallery by sphinx-gallery cxxfiles = (Glob("#samples/cxx/*/*.cpp") + Glob("#samples/cxx/*/*.h") + Glob("#samples/cxx/*.rst")) for cxxfile in cxxfiles: diff --git a/doc/sphinx/develop/index.md b/doc/sphinx/develop/index.md index c79f7641d..c13f826f2 100644 --- a/doc/sphinx/develop/index.md +++ b/doc/sphinx/develop/index.md @@ -51,6 +51,7 @@ reactor-integration This section is a work in progress. ``` +- [](CONTRIBUTING) - [](style-guidelines) - [](doc-formatting) @@ -58,6 +59,7 @@ This section is a work in progress. :caption: Adding New Features to Cantera :hidden: +CONTRIBUTING style-guidelines doc-formatting ```