Contributing to SpECTRE

Table of Contents

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:

Provide more context by answering these questions:

Include details about your configuration and environment:

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.

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:

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:

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.

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.

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:

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.

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.

If you would like feedback on a pull request prior to it being ready for formal review, please label it with in progress and ping whomever you wish to get feedback from. As long as the in progress label remains, no one should review the pull request.

Git Commit Message Guidelines

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.