2. Development Workflow¶
Anyone wishing to make contributions to OpenMC should be fully acquainted and comfortable working with git and GitHub. We assume here that you have git installed on your system, have a GitHub account, and have setup SSH keys to be able to create/push to repositories on GitHub.
Development of OpenMC relies heavily on branching; specifically, we use a branching model sometimes referred to as git flow. If you plan to contribute to OpenMC development, we highly recommend that you read the linked blog post to get a sense of how the branching model works. There are two main branches that always exist: master and develop. The master branch is a stable branch that contains the latest release of the code. The develop branch is where any ongoing development takes place prior to a release and is not guaranteed to be stable. When the development team decides that a release should occur, the develop branch is merged into master.
All new features, enhancements, and bug fixes should be developed on a branch that branches off of develop. When the feature is completed, a pull request is initiated on GitHub that is then reviewed by a committer. If the pull request is satisfactory, it is then merged into develop. Note that a committer may not review their own pull request (i.e., an independent code review is required).
2.2. Code Review Criteria¶
In order to be considered suitable for inclusion in the develop branch, the following criteria must be satisfied for all proposed changes:
Changes have a clear purpose and are useful.
Compiles and passes all tests under multiple build configurations (This is checked by Travis CI).
If appropriate, test cases are added to regression or unit test suites.
No memory leaks (checked with valgrind).
Conforms to the OpenMC style guide.
No degradation of performance or greatly increased memory usage. This is not a hard rule – in certain circumstances, a performance loss might be acceptable if there are compelling reasons.
New features/input are documented.
No unnecessary external software dependencies are introduced.
Now that you understand the basic development workflow, let’s discuss how an individual can contribute to development. Note that this would apply to both new features and bug fixes. The general steps for contributing are as follows:
Fork the main openmc repository from openmc-dev/openmc. This will create a repository with the same name under your personal account. As such, you can commit to it as you please without disrupting other developers.
Clone your fork of OpenMC and create a branch that branches off of develop:
git clone --recurse-submodules firstname.lastname@example.org:yourusername/openmc.git cd openmc git checkout -b newbranch develop
tools/dev/install-commit-hooks.shto install a post-commit hook that runs clang-format on C++ files to apply automatic code formatting (requires that clang-format already be installed). In addition, you may want to configure your text editor to automatically run clang-format when saving C++ files.
Make your changes on the new branch that you intend to have included in develop. If you have made other changes that should not be merged back, ensure that those changes are made on a different branch.
Issue a pull request from GitHub and select the develop branch of openmc-dev/openmc as the target.
At a minimum, you should describe what the changes you’ve made are and why you are making them. If the changes are related to an outstanding issue, make sure it is cross-referenced.
A committer will review your pull request based on the criteria above. Any issues with the pull request can be discussed directly on the pull request page itself.
After the pull request has been thoroughly vetted, it is merged back into the develop branch of openmc-dev/openmc.
2.4. Private Development¶
While the process above depends on the fork of the OpenMC repository being publicly available on GitHub, you may also wish to do development on a private repository for research or commercial purposes. The proper way to do this is to create a complete copy of the OpenMC repository (not a fork from GitHub). The private repository can then either be stored just locally or in conjunction with a private repository on Github (this requires a paid plan). Alternatively, Bitbucket offers private repositories for free. If you want to merge some changes you’ve made in your private repository back to openmc-dev/openmc repository, simply follow the steps above with an extra step of pulling a branch from your private repository into a public fork.
2.5. Working in “Development” Mode¶
If you are making changes to the Python API during development, it is highly suggested to install the Python API in development/editable mode using pip. From the root directory of the OpenMC repository, run:
pip install -e .[test]
This installs the OpenMC Python package in “editable” mode so that 1)
it can be imported from a Python interpreter and 2) any changes made are
immediately reflected in the installed version (that is, you don’t need to keep
reinstalling it). While the same effect can be achieved using the
PYTHONPATH environment variable, this is generally discouraged as it
can interfere with virtual environments.