Fork and PR Model

Overview

Contributions to the mpas_app project are made via a Fork and Pull Request (PR) model. GitHub provides a thorough description of this contribution model in their Contributing to a project Quickstart, but the steps, with respect to mpas_app contributions, can be summarized as:

  1. Fork the mpas_app repository into your personal GitHub account.

  2. Clone your fork onto your development system.

  3. Create an mpas_app Issue to discuss your proposed work.

  4. Create a branch in your clone for your changes.

  5. Make, commit, and push changes in your clone / to your fork. (Refer to the Developer Setup page for setting up a development shell, formatting and testing your code, etc.)

  6. When your work is complete, create a pull request to merge your changes.

For future contributions, you may delete and then recreate your fork or configure the official mpas_app repository as a remote repository on your clone and sync upstream changes to stay up-to-date with the official repository.

Specifics for mpas_app

When creating your PR, please follow these guidelines, specific to the mpas_app project:

  • Ensure that your PR is targeting base repository noaa-gsl/mpas_app and base branch main.

  • Your PR’s Add a description field will appear pre-populated with a template that you should complete. Provide an informative synopsis of your contribution, then mark appropriate checklist items by placing an “x” between their square brackets. You may tidy up the description by removing boilerplate text and non-selected checklist items.

  • Use the pull-down arrow on the green button below the description to initially create a draft pull request.

  • Once your draft PR is open, visit its Files changed tab and add comments on any lines of code that you think reviewers will benefit from. Try to save time by proactively answering questions you suspect reviewers will ask.

  • Once your draft PR is marked up with your comments, return to the Conversation tab and click the Ready for review button.

A default set of reviewers will automatically be added to your PR. You may add others, if appropriate. Reviewers may make comments, ask questions, or request changes on your PR. Respond to these as needed, making commits in your clone and pushing to your fork/branch. Your PR will automatically be updated when commits are pushed to its source branch in your fork, so reviewers will immediately see your updates.

Merging

Your PR is ready to merge when:

  1. It has been approved by a required number of mpas_app core-developer reviewers.

  2. All required checks have passed.

These criteria and their current statuses are detailed in a section at the bottom of your PR’s Conversation tab. Checks take some time to run, so please be patient.

If you have write access to the mpas_app repo, you may merge your PR yourself once the above conditions are met. If not, an mpas_app core developer will perform the merge for you.

Need Help?

Please use comments in the Conversation tab of your PR to ask for help with any difficulties you encounter using this process!