Skip to content

HAFS Code Repository Governance

KathrynNewman edited this page Jan 25, 2023 · 2 revisions

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.