Pull Requests

Pull Requests in GitHub provide an interface for others to review and test your code. Testing pull requests is a good way to start contributing to the RST.

Code Check List

Before submitting a PR, please check the following:

  • copyright and disclaimer, or modification line is added (see RST copyright & license)
  • the code compiles and runs with no additional warnings
  • the new code has been tested on your own machine
  • user documentation has been included/updated
  • the code is on its own git branch
  • all code is pushed to the remote branch on Github

Creating the PR

To create a PR, navigate to RST's Pull Requests and click on New pull request. If templates are available, select the one that is most appropriate.

Merging Direction

In general, new code should be merged to develop. Possible exceptions to this rule are:

  • if a new feature/update will be added in several stages, merge to an intermediate branch (git checkout -b from the intermediate branch)

  • merge to master ONLY if it is a HOTFIX or RELEASE branch.

    Note

    HOTFIX is a substantial fix for a bug that prevents users from installing or using RST or gives inaccurate data. Documentation fixes can also be seen as a HOTFIX as they do not require a new release or DOI.

  • Small changes to documentation can be merged to master (e.g. fixing typos)

Writing a PR

Follow the template to fill out the required sections. If there is no template, please provide the following information:

  • Informative title
  • Description of the changes you made
  • What people should focus on when testing/reviewing the code
  • How to install the code if this has changed
  • Code fragments showing how to test the code and the expected output/plots
  • Any extra details that might be useful during testing

Extra Tidbits

Pull requests on GitHub provide several additional features to help you get a useful code review:

  • Request a review from a specific person
  • Add labels to categorize the PR (e.g. bugfix, enhancement)
  • Indicate that the PR is part of a project, if applicable
  • Assign a milestone, if applicable
  • Link the PR to an issue, if applicable

Draft Pull Requests

Draft Pull Requests are a way to tell reviewers that your code is not ready to be merged yet. This might be useful in the following situations:

  • The draft PR is dependent on another PR being merged or tested first
  • The code has a major bug and you would like some assistance to fix it
  • The code needs further work, but you would like some feedback on what you have already done

Guidelines

Here are some general guidelines to follow with Pull Requests:

  • Do not merge your own code!
  • If at least 2 people have "approved" the code, anyone (including the code author) may merge it
  • Make sure your code is complete before creating a PR (to reduce additional commit emails)
  • Make sure your code is tested on various operating systems if needed
  • Optional: code is reviewed in a Code Review