diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b633bb9295..be506f919a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,8 +36,8 @@ development team will be happy to discuss it. ## How to Submit Changes All changes to OpenMC happen through pull requests. For a full overview of the -process, see the developer's guide section on [Development -Workflow](http://openmc.readthedocs.io/en/latest/devguide/workflow.html). +process, see the developer's guide section on [Contributing to +OpenMC](http://openmc.readthedocs.io/en/latest/devguide/contributing.html). ## Code Style diff --git a/docs/source/_images/fork.png b/docs/source/_images/fork.png index f43f64242e..9bc63ae612 100644 Binary files a/docs/source/_images/fork.png and b/docs/source/_images/fork.png differ diff --git a/docs/source/_images/pullrequest.png b/docs/source/_images/pullrequest.png deleted file mode 100644 index 8cfc71e9cd..0000000000 Binary files a/docs/source/_images/pullrequest.png and /dev/null differ diff --git a/docs/source/devguide/contributing.rst b/docs/source/devguide/contributing.rst new file mode 100644 index 0000000000..c08b1a362f --- /dev/null +++ b/docs/source/devguide/contributing.rst @@ -0,0 +1,129 @@ +.. _devguide_contributing: + +====================== +Contributing to OpenMC +====================== + +Thank you for considering contributing to OpenMC! We look forward to welcoming +new members to the community and will do our best to help you get up to speed. +The purpose of this section is to document how the project is managed: how +contributions (bug fixes, enhancements, new features) are made, how they are +evaluated, who is permitted to merge pull requests, and what happens in the +event of disagreements. Once you have read through this section, the +:ref:`devguide_workflow` section outlines the actual mechanics of making a +contribution (forking, submitting a pull request, etc.). + +The goal of our governance model is to: + +- Encourage new contributions. +- Encourage contributors to remain involved. +- Avoid unnecessary processes and bureaucracy whenever possible. +- Create a transparent decision making process which makes it clear how + contributors can be involved in decision making. + +Overview +-------- + +OpenMC uses a liberal contribution model for project governance. Anyone involved +in development in a non-trivial capacity is given an opportunity to influence +the direction of the project. Project decisions are made through a +consensus-seeking process rather than by voting. + +Terminology +----------- + +- A *Contributor* is any individual creating or commenting on an issue or pull + request. +- A *Committer* is a subset of contributors who are authorized to review and + merge pull requests. +- The *TC* (Technical Committee) is a group of committers who have the authority + to make decisions on behalf of the project team in order to resolve disputes. +- The *Project Lead* is a single individual who has the authority to make a final + decision when the TC is unable to reach consensus. + +Contribution Process +-------------------- + +Any change to the OpenMC repository must be made through a pull request (PR). +This applies to all changes to documentation, code, binary files, etc. Even long +term committers and TC members must use pull requests. + +No pull request may be merged without being independently reviewed. + +For non-trivial contributions, pull requests should not be merged for at least +36 hours to ensure that contributors in other timezones have time to review. +Consideration should be given to weekends and other holiday periods to ensure +active committers have reasonable time to become involved in the discussion and +review process if they wish. Any committer may request that the review period be +extended if they are unable to review the change within 36 hours. + +During review, a committer may request that a specific contributor who is most +versed in a particular area review the PR before it can be merged. + +A pull request can be merged by any committer, but only if no objections are +raised by any other committer. In the case of an objection being raised, all +involved committers should seek consensus through discussion and compromise. + +In the case of an objection being raised in a pull request by another committer, +all involved committers should seek to arrive at a consensus by way of +addressing concerns being expressed through discussion, compromise on the +proposed change, or withdrawal of the proposed change. + +If objections to a PR are made and committers cannot reach a consensus on how to +proceed, the decision is escalated to the TC. TC members should regularly +discuss pending contributions in order to find a resolution. It is expected that +only a small minority of issues be brought to the TC for resolution and that +discussion and compromise among committers be the default resolution mechanism. + +Becoming a Committer +-------------------- + +All contributors who make a non-trivial contribution will be added as a +committer in a timely manner. Committers are expected to follow this policy. + +TC Process +---------- + +Any issues brought to the TC will be addressed among the committee with a +consensus-seeking process. The group tries to find a resolution that has no +objections among TC members. If a consensus cannot be reached, the Project Lead +has the ultimate authority to make a final decision. It is expected that the +majority of decisions made by the TC are via a consensus seeking process and +that the Project Lead intercedes only as a last resort. + +Resolution may involve returning the issue to committers with suggestions on how +to move forward towards a consensus. + +Members can be added to the TC at any time. Any committer can nominate another +committer to the TC and the TC uses its standard consensus seeking process to +evaluate whether or not to add this new member. Members who do not participate +consistently at the level of a majority of the other members are expected to +resign. + +In the event that the Project Lead resigns or otherwise steps down, the TC uses +a consensus seeking process to choose a new Project Lead. + +Leadership Team +--------------- + +The TC consists of the following individuals: + +- `Paul Romano `_ +- `Sterling Harper `_ +- `Adam Nelson `_ +- `Benoit Forget `_ + +The Project Lead is Paul Romano. + +Next Steps +---------- + +If you are interested in working on a specific feature or helping to address +outstanding issues, consider joining the developer's `mailing list +`_ and/or `Slack community +`_. Note that some issues have specifically +been labeled as good for `first-time contributors +`_. +Once you're at the point of writing code, make sure your read through the +:ref:`devguide_workflow` section to understand the mechanics of making pull +requests and what is expected during code reviews. diff --git a/docs/source/devguide/index.rst b/docs/source/devguide/index.rst index e40e7f6359..e2410f080d 100644 --- a/docs/source/devguide/index.rst +++ b/docs/source/devguide/index.rst @@ -4,16 +4,17 @@ Developer's Guide ================= -Welcome to the OpenMC Developer's Guide! This guide documents and explains the -structure of the OpenMC source code and how to do various development tasks such -as debugging. +Welcome to the OpenMC Developer's Guide! This guide documents how contributions +are made to OpenMC, what style rules exist for the code, how to run tests, and +other related topics. .. toctree:: :numbered: :maxdepth: 2 - styleguide + contributing workflow + styleguide tests user-input docbuild diff --git a/docs/source/devguide/workflow.rst b/docs/source/devguide/workflow.rst index 6201f429a0..31dc088428 100644 --- a/docs/source/devguide/workflow.rst +++ b/docs/source/devguide/workflow.rst @@ -22,13 +22,11 @@ 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 +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 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). +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). Code Review Criteria -------------------- @@ -37,9 +35,9 @@ 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 the regression suite with all configurations (This is +- Compiles and passes all tests under multiple build configurations (This is checked by Travis CI). -- If appropriate, test cases are added to regression suite. +- 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 @@ -76,13 +74,11 @@ features and bug fixes. The general steps for contributing are as follows: 4. Issue a pull request from GitHub and select the *develop* branch of openmc-dev/openmc as the target. - .. image:: ../_images/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. -5. A trusted developer will review your pull request based on the criteria +5. 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. @@ -133,6 +129,4 @@ can interfere with virtual environments. .. _openmc-dev/openmc: https://github.com/openmc-dev/openmc .. _paid plan: https://github.com/plans .. _Bitbucket: https://bitbucket.org -.. _ctest: http://www.cmake.org/cmake/help/v2.8.12/ctest.html -.. _NNDC: http://www.nndc.bnl.gov/endf/b7.1/acefiles.html .. _pip: https://pip.pypa.io/en/stable/ diff --git a/docs/source/io_formats/summary.rst b/docs/source/io_formats/summary.rst index 76c412b860..1f30c69bb1 100644 --- a/docs/source/io_formats/summary.rst +++ b/docs/source/io_formats/summary.rst @@ -123,7 +123,8 @@ The current version of the summary file format is 6.0. **/macroscopics/** -:Attributes: - **n_macroscopics** (*int*) -- Number of macroscopic data sets +:Attributes: + - **n_macroscopics** (*int*) -- Number of macroscopic data sets in the problem. :Datasets: - **names** (*char[][]*) -- Names of the macroscopic data sets.