SpECTRE  v2024.06.05
Contributing to SpECTRE

Contributing to SpECTRE

The following is a set of guidelines for contributing to SpECTRE, which is hosted in the Simulating eXtreme Spacetimes Organization on GitHub.

Code of Conduct

This project and everyone participating in it is governed by the SpECTRE Code of Conduct. By participating, you are expected to uphold this code. Please report possible violations of the code of conduct to condu.nosp@m.ct@s.nosp@m.pectr.nosp@m.e-co.nosp@m.de.or.nosp@m.g.

What should I know before I get started?

SpECTRE is being developed in support of our collaborative Simulating eXtreme Spacetimes (SXS) research program into the multi-messenger astrophysics of neutron star mergers, core-collapse supernovae, and gamma-ray bursts. As such, almost all of the current contributors to SpECTRE are members of SXS institutions, and a large amount of discussion about SpECTRE is done in internal SXS meetings. If you are a member of SXS and wish to get involved, please contact one of the project leaders.

In the future, we hope that SpECTRE can be applied to problems across discipline boundaries, and that it can be a true community code. At the present time, however, SpECTRE cannot yet solve realistic problems, and broad overview documentation is in an early, incomplete stage. Therefore, if you are not a member of SXS, but are interested in contributing to SpECTRE, we strongly encourage you to contact us at quest.nosp@m.ions.nosp@m.@spec.nosp@m.tre-.nosp@m.code..nosp@m.org to discuss possible contributions.

How Can I Contribute?

Reporting Bugs

This section guides you through submitting a bug report for SpECTRE. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.

Before creating bug reports, please perform a search to see if the problem has already been reported. If it has and the issue is still open, please add a comment to the existing issue instead of opening a new one.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, please open a new issue and include a link to the original issue in the body of your new one.

How Do I Submit A (Good) Bug Report?

Bugs are tracked as GitHub issues. When you are creating a bug report, please include as many details as possible. Please fill out the template completely. The provided information helps us resolve issues faster.

Explain the problem and include additional details to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps which reproduce the problem in as much detail as possible. For example, start by explaining how you started SpECTRE, e.g. the exact command you used in the terminal, or the contents of the batch job script you used.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
  • Explain which behavior you expected to see instead and why.

Provide more context by answering these questions:

  • Can you reproduce the problem in both debug and release mode? (this is controlled by the CMake flag CMAKE_BUILD_TYPE)
  • Did the problem start happening recently (e.g. after updating to a new version/commit of SpECTRE) or was this always a problem?
  • If the problem started happening recently, can you reproduce the problem in an older version/commit? What's the most recent version/commit in which the problem doesn't happen?
  • Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
  • Can you reproduce the problem on another machine?
  • Can you reproduce the problem in the docker container? (see the Installation notes)

Include details about your configuration and environment:

  • Add as an attachment (or add the contents of) the following:
    • The text output by SpECTRE (including any stack trace)
    • The input file(s)
    • $SPECTRE_BUILD_DIR/BuildInfo.txt
  • What is the name and version of the OS you're using?
  • If possible (for SXS computers or HPC systems), a path to a run directory that is accessible by SpECTRE core developers.

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for SpECTRE, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.

Before creating enhancement suggestions, please perform a search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.

How Do I Submit A (Good) Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues. When you are creating an enhancement suggestion, please include as many details as possible as you fill in the template.

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Explain why this enhancement would be useful to most SpECTRE users.

Your First Code Contribution

Unsure where to begin contributing to SpECTRE? You can start by looking through these good first issue and help wanted issues:

  • Good first issues - issues which should only require a few lines of code, and a test or two.
  • Help wanted issues - issues which should be a bit more involved than good first issues.

Local development

SpECTRE can be developed locally. For instructions on how to do this, see the following sections in the SpECTRE documentation:

Pull Requests

Code contributions to SpECTRE follow a pull request model

The process described here has several goals:

  • Maintain SpECTRE's code and documentation quality
  • Reach science goals in a timely manner
  • Fix problems that are important to users
  • Engage the community in working toward the best possible code
  • Enable a sustainable system for SpECTRE's maintainers to review contributions

Please follow these steps to have your contribution considered by the maintainers:

  1. Follow the code review guidelines, the guide to writing unit tests, and the guide to writing documentation
  2. Follow all instructions in the pull request template. Reference related issues and pull requests.
  3. After you submit your pull request, verify that all status checks are passing

‍If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.

Only those status check failures that occur in the containerized build environment are your responsibility to fix. If you encounter an issue with a status check that runs in an environment that you do not have access to, e.g. on macOS or on a supercomputer, please notify @sxs-collaboration/spectre-core-devs. They will refer the issue to a person who has access to that environment. Unless requested by the reviewers, the PR will not be held up until the issue is resolved.

While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewers may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.

How SpECTRE pull request reviews are conducted

‍Note that these are guidelines and not rigid rules.

Please make your pull requests as small as reasonably possible, as smaller pull requests are easier to review. In general, longer pull requests take longer to review, with the time scaling exponentially with the number of lines changed. Therefore if your pull request is too large, we may ask you to break it up into several smaller pull requests.

If you would like feedback on a pull request prior to it being ready for formal review, please open it in draft mode and request reviews from whomever you wish to get feedback from. As long as the PR is in draft mode it will not be reviewed, aside from the feedback requested.

‍Below, days mean business days, so if the time period includes the weekend, add two days, and for major holidays add a day. Furthermore, most of us are academics, and we occasionally go to conferences which may lead to delays in the review process. Also do not expect much to happen between December 20th and January 3rd.

Most pull requests submitted to SpECTRE will be reviewed in the following manner:

  • Within two days, one of the SpECTRE core developers will either review the PR or assign reviewers. If this has not happened after two days, please request a review and select the @sxs-collaboration/spectre-core-devs team. Also feel free to ping the core developers (e.g @sxs-collaboration/spectre-core-devs please assign reviewers) if they fail to respond in a timely manner.
  • Assigned reviewers should either confirm that they are able to review (by reviewing or providing a reasonable timeframe for their review) or decline within two days so another reviewer can be assigned.
  • Anyone is welcome to self-assign themselves as a reviewer.
  • Assigned reviewers should submit their review in as timely a manner as possible.
  • Anyone can request changes within either the first two days of the pull request, or within a day after the initial reviews of the assigned reviewers. After this period, only the assigned reviewers can request changes, unless someone believes the code is wrong. Non-reviewers are allowed to make comments, which the pull request author is encouraged to address. Alternatively the author can create an issue with the suggested changes, assigned to themselves, which would then be addressed in a subsequent pull request by the author.
  • If any requested change is unclear to the author, they should ping the reviewer and ask for clarification. Authors and reviewers are encouraged to talk to one another (in person, via Google hangout, or some other verbal method if possible) to resolve any issues.
  • Reviewers are encouraged to ping others @GITHUB_USERNAME to get opinions on code they are unsure about.
  • It is permissible to have a group code review led by one of the reviewers. The reviewer should comment on who was present at the group review.
  • If necessary, pull requests can also be discussed at one of the weekly SpECTRE meetings.
  • If changes are requested, the author should fix all of them in one or more fixup commits (where the first line of the commit message should begin with fixup) and push them to the PR branch. Fixup commits make reviews significantly faster because the reviewers don't have to review the full PR again, but only the parts that changed.
  • After pushing fixup commits, the author should re-request reviews from the reviewers. They can also ping the reviewers that the pull request is updated.
  • Once a pull request is updated, the reviewers should either request further changes or approve the PR.
  • Once all reviewers have approved the PR or given the okay to squash, the author should rebase on develop and then squash their commits into one or more self-contained commits (such that the code will compile and pass all tests after each commit). The squashed commits will need to be force pushed.
  • Once all reviewers have approved the pull request, someone should ping the @sxs-collaboration/spectre-core-devs. If one of the original reviewers is a core developer, this is not necessary and the core developer can merge the pull request.
  • One of the core developers will perform a final cursory review, requesting changes only for major problems, and commenting on other possible changes.
  • The pull request author should address all final requested changes and may either also fix final suggested changes, or create an issue with the suggested changes, which will be addressed in a subsequent pull request by the author.
  • The SpECTRE core developer will merge the pull request once all comments have been addressed, all reviewers have approved the PR, the code passes CI and all pull requests the pull request depends on have been merged. When approvals are dismissed by minor changes, such as rebasing, squashing fixup commits or adding a missing include, the core developer may merge the PR without waiting for all reviewers to re-approve the PR.

In addition to the guidelines above, we apply the following exceptions based on the type of change:

  • Critical bug fixes (i.e. the code is broken) can be merged after two expedited reviews by SpECTRE core developers. If necessary, an issue can be created if further changes are desired.
  • PRs that add documentation don't need to be perfect, since having some docs is better than having none. Reviewers should approve after one or at most two rounds of review and allow further minor changes to be done in follow-ups.
  • "Small" or "trivial" PRs can be merged immediately by core developers. Examples for such PRs are:

    • Fixing typos in documentation or adding (small amounts of) documentation
    • Fixing missing includes or missing linked libraries
    • Adding Python bindings
    • Formatting code
    • Refactoring, renaming or moving files with no change in functionality (unless potentially controversial)

    It is the reviewing core developer's responsibility to decide if the PR is "small" or "trivial" enough to merge immediately. If they are unsure, they should fall back to the usual procedure of giving people two days to assign themselves as reviewers and/or reach out to whoever they think might want to review the PR.

  • Pull requests that are designated new design are expected to have a longer review period, including discussions during weekly SpECTRE meetings. SpECTRE core developers will provide reasonable review deadlines once the new design is finalized.

Git Commit Message Guidelines

  • Use the present tense ("Add feature" not "Added feature")
  • Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line to 72 characters or less
  • If needed, a blank second line followed by a more complete description

SpECTRE core developers

SpECTRE core developers are people who are very familiar with the entire code, comfortable with modern C++, and willing to take the responsibility of overseeing the code as a whole. Current SpECTRE core developers can be pinged on GitHub at @sxs-collaboration/spectre-core-devs. It is expected that as more contributors become familiar with SpECTRE, additional people will be added to the list of core developers.