mirror of
https://github.com/openmc-dev/openmc.git
synced 2026-07-27 13:45:36 -04:00
Expand description of OpenMC development workflow.
This commit is contained in:
Paul Romano
parent
975fd21284
commit
4ebeb3a8bb
1 changed files with 90 additions and 21 deletions
|
|
@ -5,41 +5,110 @@ Development Workflow
|
|||
====================
|
||||
|
||||
Anyone wishing to make contributions to OpenMC should be fully acquianted and
|
||||
comfortable working with git_ and GitHub_. The primary means of modifying and
|
||||
making contributions to OpenMC is through GitHub `pull requests`_. This is
|
||||
what's known as a fork and pull development model. The steps for this are as
|
||||
follows:
|
||||
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.
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
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*.
|
||||
|
||||
Trivial changes to the code may be committed directly to the *develop* branch by
|
||||
a trusted developer. However, most new features 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 trusted developer. If the pull
|
||||
request is satisfactory, it is then merged into *develop*. Note that a trusted
|
||||
developer may not review their own pull request (i.e., an independent code
|
||||
review is required).
|
||||
|
||||
Code Review Criteria
|
||||
--------------------
|
||||
|
||||
In order to be consider suitable for for inclusion in the *develop* branch, the
|
||||
following criteria must be satisfied for all proposed changes:
|
||||
|
||||
- Compiles under all conditions (MPI, OpenMP, HDF5, etc.). This is checked as
|
||||
part of the test suite (see `test_compile.py`_).
|
||||
- Passes the regression suite.
|
||||
- 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.
|
||||
|
||||
Contributing
|
||||
------------
|
||||
|
||||
Now that you understand the basic development workflow, let's discuss how an
|
||||
individual to contribute to development. Note that this would apply to both new
|
||||
features and bug fixes. The general steps for contributing are as follows:
|
||||
|
||||
1. Fork the main openmc repository from `mit-crpg/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.
|
||||
repository with the same name under your personal account. As such, you can
|
||||
commit to it as you please without disrupting other developers.
|
||||
|
||||
2. Create a branch that you want merged back to `mit-crpg/openmc`_ and make
|
||||
commits that you intend to go back. If you have made other changes that should
|
||||
not be merged back, those changes should be on another branch.
|
||||
.. image:: ../../img/fork.png
|
||||
|
||||
3. Issue a pull request from GitHub and select the branch you want merged.
|
||||
2. Clone your fork of OpenMC and create a branch that branches off of *develop*:
|
||||
|
||||
4. The OpenMC integration manager will review your pull request and make sure it
|
||||
conforms to the :ref:`devguide_styleguide`, compiles correctly, runs in parallel
|
||||
correctly, does not break other features in the code, etc. Any issues with the
|
||||
pull request can be discussed directly on the pull request page itself.
|
||||
.. code-block:: sh
|
||||
|
||||
5. After the pull request has been thoroughly vetted, it is merged back into
|
||||
`mit-crpg/openmc`_.
|
||||
git clone git@github.com:yourusername/openmc.git
|
||||
cd openmc
|
||||
git checkout -b newbranch develop
|
||||
|
||||
3. 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.
|
||||
|
||||
4. Issue a pull request from GitHub and select the *develop* branch of
|
||||
mit-crpg/openmc as the target.
|
||||
|
||||
.. image:: ../../img/pullrequest.png
|
||||
|
||||
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 oustanding issue, make
|
||||
sure it is cross-referenced. A wise developer would also check whether their
|
||||
changes do indeed pass the regression test suite.
|
||||
|
||||
5. A trusted developer 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.
|
||||
|
||||
6. After the pull request has been thoroughly vetted, it is merged back into the
|
||||
*develop* branch of mit-crpg/openmc.
|
||||
|
||||
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`_). If you want to
|
||||
merge some changes you've made in your private repository back to
|
||||
`mit-crpg/openmc`_ repository, simply follow the steps above with an extra step
|
||||
of pulling a branch from your private repository into your public fork.
|
||||
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 mit-crpg/openmc
|
||||
repository, simply follow the steps above with an extra step of pulling a branch
|
||||
from your private repository into a public fork.
|
||||
|
||||
.. _git: http://git-scm.com/
|
||||
.. _GitHub: https://github.com/
|
||||
.. _pull requests: https://help.github.com/articles/using-pull-requests
|
||||
.. _git flow: http://nvie.com/git-model
|
||||
.. _test_compile.py: https://github.com/mit-crpg/openmc/blob/develop/tests/test_compile/test_compile.py
|
||||
.. _valgrind: http://valgrind.org/
|
||||
.. _style guide: http://mit-crpg.github.io/openmc/devguide/styleguide.html
|
||||
.. _pull request: https://help.github.com/articles/using-pull-requests
|
||||
.. _mit-crpg/openmc: https://github.com/mit-crpg/openmc
|
||||
.. _paid plan: https://github.com/plans
|
||||
.. _Bitbucket: https://bitbucket.org
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue