HAFS Code Repository Governance

Getting Started

• Developers are strongly encouraged to discuss their plans with the HAFS Developers committee before starting work.
  • The group meets on a roughly biweekly basis and includes EMC, DTC, and other community members. They will provide feedback on the proposed development and ensure that it is well coordinated with other efforts.
  • Developers should contact Kathryn Newman (knewmanATucarDOTedu) to be added to the agenda for a future meeting.
• Developers are encouraged to perform their work in the HAFS community repositories on GitHub (e.g., https://github.com/hafs-community/HAFS). However, a developer may choose to use personal forks for their development instead.
  • Personal forks are appropriate when the development does not involve much collaboration with other HAFS developers and/or when the developer does not have write access to the hafs-community repositories.
• Within the hafs-community/HAFS repository, developers should create a new GitHub issue with a short description of the planned work to make the community aware of it.
• All developers should create a branch at the HAFS application level that begins with “feature/” and ends with a short name that describes the planned work (e.g., feature/hafs_ensda or feature/moving_nest).
  • The branch should generally be based on the develop branch, unless there is a good reason to start from a different branch.
• If a developer plans to modify one or more submodules, they should make branches in each submodule repository (within HAFS community) that they plan to modify.
  • Use the same branch name as the one used above.
  • Branches should generally be based on the support/HAFS branch of each submodule, unless there is a good reason to start from a different branch.
• Push your new branch(es) to the remote repository and begin your development work.

Performing Development

• All development should take place within a branch as discussed above.
• Developers are strongly encouraged to sync with the develop branch (at the application level) and the support/HAFS branches for submodules on a regular basis.
• Developers should commit work to their branch on a regular basis and provide commit messages that accurately reflect the changes made.

Submitting a Pull Request

• When development is complete and it is time to submit a pull request, developers should ensure their branch is up to date with the latest commits from the develop branch at the application level and from the support/HAFS branches for each submodule.
• After merging in any new commits, developers should retest their code and ensure that it is working as expected.
• Once all testing is complete, developers should submit a pull request on GitHub. Separate pull requests are needed for each submodule that the developer changes, including all nested submodules down to the level of the change.
  • The pull request should include a concise message that explains the purpose of the changes. If the developer created an issue to describe their development, the pull request should reference the issue number.
  • The HAFS repository code owners will be tagged automatically as reviewers. The developer may also designate additional reviewers for their work.
  • The developer should tag BinLiu-NOAA, ZhanZhang-NOAA, KathrynNewman, and panll as the approvers.

Review and Approval

• Reviewers are encouraged to either approve or suggest changes to the pull request within five working days when the pull request is next in line for review.
• If changes are requested, developers should either implement them (and retest) or explain why they think the changes are not necessary by engaging in a dialogue with the reviewers in the pull request.
• When, after five days, two or more reviewers have approved the pull request and all reviewer comments have been addressed or resolved, the pull request will be merged by the approver.
  • The approver has the discretion to either use a squash merge or a regular merge depending on the nature of the changes.
• After merging, unless further development related to the original work is anticipated, the developer should delete any branches that they created. Unrelated additional development should take place in new branches.