SpECTRE
v2024.09.29
|
The following is a set of guidelines for contributing to SpECTRE, which is hosted in the Simulating eXtreme Spacetimes Organization on GitHub.
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.
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.
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.
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:
CMAKE_BUILD_TYPE
)Include details about your configuration and environment:
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.
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.
Unsure where to begin contributing to SpECTRE? You can start by looking through these good first issue
and help wanted
issues:
good first issue
s.SpECTRE can be developed locally. For instructions on how to do this, see the following sections in the SpECTRE documentation:
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:
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.
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:
@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.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.@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.In addition to the guidelines above, we apply the following exceptions based on the type of change:
"Small" or "trivial" PRs can be merged immediately by core developers. Examples for such PRs are:
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.
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.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.