SpECTRE Documentation Coverage Report
Current view: top level - __w/spectre/spectre/docs - CONTRIBUTING.md Hit Total Coverage
Commit: 2db722c93a8e9b106e406b439b79c8e05c2057fb Lines: 0 1 0.0 %
Date: 2021-03-03 22:01:00
Legend: Lines: hit not hit

          Line data    Source code
       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : 
       6             : 
       7             : # Contributing to SpECTRE {#contributing_to_spectre}
       8             : 
       9             : \tableofcontents
      10             : 
      11             : # Contributing to SpECTRE {#contributing_to_spectre_2}
      12             : 
      13             : The following is a set of guidelines for contributing to SpECTRE,
      14             : which is hosted in the [Simulating eXtreme Spacetimes
      15             : Organization](https://github.com/sxs-collaboration) on GitHub.
      16             : 
      17             : ## Code of Conduct
      18             : 
      19             : This project and everyone participating in it is governed by the \ref
      20             : code_of_conduct "SpECTRE Code of Conduct". By participating, you are
      21             : expected to uphold this code. Please report possible violations of the
      22             : code of conduct to conduct@spectre-code.org.
      23             : 
      24             : ## What should I know before I get started? {#getting-started}
      25             : 
      26             : SpECTRE is being developed in support of our collaborative Simulating
      27             : eXtreme Spacetimes (SXS) research program into the multi-messenger
      28             : astrophysics of neutron star mergers, core-collapse supernovae, and
      29             : gamma-ray bursts.  As such, almost all of the current contributors to
      30             : SpECTRE are members of SXS institutions, and a large amount of
      31             : discussion about SpECTRE is done in internal SXS meetings.  If you are
      32             : a member of SXS and wish to get involved, please contact one of the
      33             : project leaders.
      34             : 
      35             : In the future, we hope that SpECTRE can be applied to problems across
      36             : discipline boundaries, and that it can be a true community code.  At
      37             : the present time, however, SpECTRE cannot yet solve realistic
      38             : problems, and broad overview documentation is in an early, incomplete
      39             : stage.  Therefore, if you are not a member of SXS, but are interested
      40             : in contributing to SpECTRE, we strongly encourage you to contact us at
      41             : questions@spectre-code.org to discuss possible contributions.
      42             : 
      43             : ## How Can I Contribute? {#how-can-i-contribute}
      44             : 
      45             : ### Reporting Bugs {#reporting-bugs}
      46             : 
      47             : This section guides you through submitting a bug report for
      48             : SpECTRE. Following these guidelines helps maintainers and the
      49             : community understand your report, reproduce the behavior, and find
      50             : related reports.
      51             : 
      52             : Before creating bug reports, please **perform a
      53             : [search](https://github.com/sxs-collaboration/spectre/issues)** to see
      54             : if the problem has already been reported. If it has **and the issue is
      55             : still open**, please add a comment to the existing issue instead of
      56             : opening a new one.
      57             : 
      58             : > **Note:** If you find a **Closed** issue that seems like it is the
      59             : > same thing that you're experiencing, please open a new issue and
      60             : > include a link to the original issue in the body of your new one.
      61             : 
      62             : #### How Do I Submit A (Good) Bug Report? {#submit-bug-report}
      63             : 
      64             : Bugs are tracked as [GitHub
      65             : issues](https://guides.github.com/features/issues/). When you are
      66             : creating a bug report, please **include as many details as
      67             : possible**. Please fill out the template completely.  The provided
      68             : information helps us resolve issues faster.
      69             : 
      70             : Explain the problem and include additional details to help maintainers
      71             : reproduce the problem:
      72             : 
      73             : * **Use a clear and descriptive title** for the issue to identify the
      74             :   problem.
      75             : * **Describe the exact steps which reproduce the problem** in as much
      76             :   detail as possible. For example, start by explaining how you started
      77             :   SpECTRE, e.g. the exact command you used in the terminal, or the
      78             :   contents of the batch job script you used.
      79             : * **Describe the behavior you observed after following the steps** and
      80             :   point out what exactly is the problem with that behavior.
      81             : * **Explain which behavior you expected to see instead and why.**
      82             : 
      83             : Provide more context by answering these questions:
      84             : 
      85             : * **Can you reproduce the problem in both debug and release mode?**
      86             : (this is controlled by the CMake flag `CMAKE_BUILD_TYPE`)
      87             : * **Did the problem start happening recently** (e.g. after updating to
      88             :   a new version/commit of SpECTRE) or was this always a problem?
      89             : * If the problem started happening recently, **can you reproduce the
      90             :   problem in an older version/commit?** What's the most recent
      91             :   version/commit in which the problem doesn't happen?
      92             : * **Can you reliably reproduce the issue?** If not, provide details
      93             :   about how often the problem happens and under which conditions it
      94             :   normally happens.
      95             : * **Can you reproduce the problem on another machine?**
      96             : * **Can you reproduce the problem in the docker container?** (see the
      97             :   \ref installation "Installation notes")
      98             : 
      99             : Include details about your configuration and environment:
     100             : 
     101             : * **Add as an attachment** (or add the contents of) the following:
     102             :   - The text output by SpECTRE (including any stack trace)
     103             :   - The input file(s)
     104             :   - $SPECTRE_BUILD_DIR/LibraryVersions.txt
     105             : * **What is the name and version of the OS you're using**?
     106             : * If possible (for SXS computers or HPC systems), a **path to a run
     107             :   directory** that is accessible by SpECTRE core developers.
     108             : 
     109             : ### Suggesting Enhancements {#suggesting-enhancements}
     110             : 
     111             : This section guides you through submitting an enhancement suggestion
     112             : for SpECTRE, including completely new features and minor improvements
     113             : to existing functionality. Following these guidelines helps
     114             : maintainers and the community understand your suggestion and find
     115             : related suggestions.
     116             : 
     117             : Before creating enhancement suggestions, please **perform a
     118             : [search](https://github.com/sxs-collaboration/spectre/issues)** to see
     119             : if the enhancement has already been suggested. If it has, add a
     120             : comment to the existing issue instead of opening a new one.
     121             : 
     122             : #### How Do I Submit A (Good) Enhancement Suggestion? {#submit-enhancement}
     123             : 
     124             : Enhancement suggestions are tracked as [GitHub
     125             : issues](https://guides.github.com/features/issues/).  When you are
     126             : creating an enhancement suggestion, please **include as many details
     127             : as possible** as you fill in the template.
     128             : 
     129             : * **Use a clear and descriptive title** for the issue to identify the
     130             :   suggestion.
     131             : * **Provide a step-by-step description of the suggested enhancement**
     132             :   in as many details as possible.
     133             : * **Explain why this enhancement would be useful** to most SpECTRE users.
     134             : 
     135             : ### Your First Code Contribution {#first-code-contribution}
     136             : 
     137             : Unsure where to begin contributing to SpECTRE? You can start by
     138             : looking through these `good first issue` and `help wanted` issues:
     139             : 
     140             : * [Good first issues][good-first-issue] - issues which should only
     141             :   require a few lines of code, and a test or two.
     142             : * [Help wanted issues][help-wanted] - issues which should be a bit
     143             :   more involved than `good first issue`s.
     144             : 
     145             : #### Local development {#local-development}
     146             : 
     147             : SpECTRE can be developed locally. For instructions on how to do this,
     148             : see the following sections in the [SpECTRE
     149             : documentation](https://spectre-code.org/):
     150             : 
     151             : * [Installing SpECTRE](installation.html)
     152             : * [Running Status Checks Locally](travis_guide.html#perform-checks-locally)
     153             : 
     154             : ## Pull Requests {#pull-requests}
     155             : 
     156             : Code contributions to SpECTRE follow a [pull request
     157             : model](https://help.github.com/articles/about-pull-requests/)
     158             : 
     159             : The process described here has several goals:
     160             : 
     161             : - Maintain SpECTRE's code and documentation quality
     162             : - Reach science goals in a timely manner
     163             : - Fix problems that are important to users
     164             : - Engage the community in working toward the best possible code
     165             : - Enable a sustainable system for SpECTRE's maintainers to review
     166             :   contributions
     167             : 
     168             : Please follow these steps to have your contribution considered by the
     169             : maintainers:
     170             : 
     171             : 1. Follow the \ref code_review_guide "code review guidelines", the
     172             :   \ref writing_unit_tests "guide to writing unit tests", and the \ref
     173             :   writing_good_dox "guide to writing documentation"
     174             : 2. Follow all instructions in the pull request template. Reference
     175             :    related issues and pull requests.
     176             : 3. After you submit your pull request, verify that all [status
     177             :    checks](https://help.github.com/articles/about-status-checks/) are
     178             :    passing
     179             : 
     180             :    > If a status check is failing, and you believe that the failure is
     181             :    > unrelated to your change, please leave a comment on the pull
     182             :    > request explaining why you believe the failure is unrelated. A
     183             :    > maintainer will re-run the status check for you. If we conclude
     184             :    > that the failure was a false positive, then we will open an issue
     185             :    > to track that problem with our status check suite.
     186             : 
     187             :    Only those status check failures that occur in the containerized build
     188             :    environment are your responsibility to fix. If you encounter an issue with a
     189             :    status check that runs in an environment that you do not have access to, e.g.
     190             :    on macOS or on a supercomputer, please notify
     191             :    `@sxs-collaboration/spectre-core-devs`. They will refer the issue to a person
     192             :    who has access to that environment. Unless requested by the reviewers, the PR
     193             :    will not be held up until the issue is resolved.
     194             : 
     195             : While the prerequisites above must be satisfied prior to having your
     196             : pull request reviewed, the reviewers may ask you to complete
     197             : additional design work, tests, or other changes before your pull
     198             : request can be ultimately accepted.
     199             : 
     200             : ## How SpECTRE pull request reviews are conducted {#pull-request-reviews}
     201             : 
     202             : > Note that these are guidelines and not rigid rules.
     203             : 
     204             : Please make your pull requests as small as reasonably possible, as
     205             : smaller pull requests are easier to review. In general, longer pull
     206             : requests take longer to review, with the time scaling exponentially
     207             : with the number of lines changed.  Therefore if your pull request is
     208             : too large, we may ask you to break it up into several smaller pull
     209             : requests.
     210             : 
     211             : > Below, days mean business days, so if the time period includes the
     212             : > weekend, add two days, and for major holidays add a day.
     213             : > Furthermore, most of us are academics, and we occasionally go to
     214             : > conferences which may lead to delays in the review process.  Also do
     215             : > not expect much to happen between December 20th and January 3rd.
     216             : 
     217             : Most pull requests submitted to SpECTRE will be reviewed in the
     218             : following manner:
     219             : - When creating the pull request, the author should add the
     220             :   appropriate labels.  If the pull request is not a `new design` or
     221             :   `in progress` (discussed below), the author may either assign two
     222             :   reviewers (if GitHub suggested any) or add the `reviewers wanted`
     223             :   label.
     224             : - Within two days, assigned reviewers should either confirm that they
     225             :   are able to review, or remove themselves while adding the `reviewers
     226             :   wanted` label.
     227             : - Anyone is welcome to self-assign themselves as a reviewer; when
     228             :   there are at least two reviewers, the `reviewers wanted` label
     229             :   should be removed.
     230             : - If there are not two reviewers after two days, a [SpECTRE core
     231             :   developer](#core-developers) will assign reviewers, removing the
     232             :   `reviewers wanted` label.  If for some reason, no reviewers have
     233             :   been assigned after three days, the author of the pull request
     234             :   should feel free to [ping the core
     235             :   developers](https://github.blog/2011-03-23-mention-somebody-they-re-notified/)
     236             :   (e.g `@sxs-collaboration/spectre-core-devs please assign reviewers`)
     237             : - Assigned reviewers should submit their review in as timely a manner
     238             :   as possible.
     239             : - Anyone can request changes within either the first two days of the
     240             :   pull request, or within a day after the initial reviews of the
     241             :   assigned reviewers.  After this period, only the assigned reviewers
     242             :   can request changes, unless someone believes the code is wrong.
     243             :   Non-reviewers are allowed to make comments, which the pull request
     244             :   author is encouraged to address.  Alternatively the author can
     245             :   create an issue with the suggested changes, assigned to themselves,
     246             :   which would then be addressed in a subsequent pull request by the
     247             :   author.
     248             : - If any requested change is unclear to the author, they should ping
     249             :   the reviewer and ask for clarification.  Authors and reviewers are
     250             :   encouraged to talk to one another (in person, via Google hangout, or
     251             :   some other verbal method if possible) to resolve any issues.
     252             : - Reviewers are encouraged to [ping others
     253             :   \@GITHUB_USERNAME](https://github.blog/2011-03-23-mention-somebody-they-re-notified/)
     254             :   to get opinions on code they are unsure about.
     255             : - It is permissible to have a group code review led by one of the
     256             :   reviewers. The reviewer should comment on who was present at the
     257             :   group review.
     258             : - If necessary, pull requests can also be discussed at one of the
     259             :   weekly SpECTRE meetings.
     260             : - If changes are requested, the author should fix all of them in one
     261             :   or more fixup commits (where the first line of the commit message
     262             :   should begin with `fixup`), and then ping the reviewers that the
     263             :   pull request is updated.  In addition the `updated` label can be
     264             :   added.
     265             : - Once a pull request is updated, the reviewers should either request
     266             :   further changes (removing the `updated` label) or tell the pull
     267             :   request author to squash their commits.
     268             : - Once all reviewers give the okay to squash, the author should
     269             :   [rebase on develop and then squash their
     270             :   commits](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
     271             :   into one or more self-contained commits (such that the code will
     272             :   compile and pass all tests after each commit).  The squashed commits
     273             :   will need to be force pushed.
     274             : - Once the commits are squashed, the author should ping the reviewers.
     275             : - Once all reviewers have approved the pull request, someone should
     276             :   ping the `@sxs-collaboration/spectre-core-devs`.  If one of the
     277             :   original reviewers is a core developer, this is not necessary and
     278             :   the core developer can merge the pull request.
     279             : - One of the core developers will perform a final cursory review,
     280             :   requesting changes only for major problems, and commenting on other
     281             :   possible changes.
     282             : - The pull request author should address all final requested changes
     283             :   and may either also fix final suggested changes, or create an issue
     284             :   with the suggested changes, which will be addressed in a subsequent
     285             :   pull request by the author.
     286             : - The SpECTRE core developer will merge the pull request once all comments have
     287             :   been addressed, all reviewers have approved the PR, the code passes CI and all
     288             :   pull requests the pull request depends on have been merged. When approvals are
     289             :   dismissed by minor changes, such as rebasing, squashing fixup commits or
     290             :   adding a missing include, the core developer may merge the PR without waiting
     291             :   for all reviewers to re-approve the PR.
     292             : 
     293             : Critical bug fixes (i.e. the code is broken) can be merged after two
     294             : expedited reviews by SpECTRE core developers.  If necessary, an issue
     295             : can be created if further changes are desired.
     296             : 
     297             : Pull requests that are designated `new design` are expected to have a
     298             : longer review period, including discussions during weekly SpECTRE
     299             : meetings.  SpECTRE core developers will provide reasonable review
     300             : deadlines once the new design is finalized.
     301             : 
     302             : If you would like feedback on a pull request prior to it being ready
     303             : for formal review, please label it with `in progress` and ping
     304             : whomever you wish to get feedback from.  As long as the `in progress`
     305             : label remains, no one should review the pull request.
     306             : 
     307             : 
     308             : ### Git Commit Message Guidelines {#git-commit-messages}
     309             : 
     310             : * Use the present tense ("Add feature" not "Added feature")
     311             : * Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
     312             : * Limit the first line to 72 characters or less
     313             : * If needed, a blank second line followed by a more complete description
     314             : 
     315             : ### SpECTRE core developers {#core-developers}
     316             : 
     317             : SpECTRE core developers are people who are very familiar with the
     318             : entire code, comfortable with modern C++, and willing to take the
     319             : responsibility of overseeing the code as a whole.
     320             : [Current SpECTRE core
     321             : developers](https://github.com/orgs/sxs-collaboration/teams/spectre-core-devs)
     322             : can be pinged on GitHub at `@sxs-collaboration/spectre-core-devs`.  It
     323             : is expected that as more contributors become familiar with SpECTRE,
     324             : additional people will be added to the list of core developers.
     325             : 
     326             : 
     327             : [good-first-issue]:https://github.com/sxs-collaboration/spectre/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+sort%3Acomments-desc
     328             : [help-wanted]:https://github.com/sxs-collaboration/spectre/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+sort%3Acomments-desc
     329             : 

Generated by: LCOV version 1.14