1. Contributing to the Global Workflow
This section is devoted to developers who wish to contribute to the Global Workflow repository.
1.1. Code managers
Kate Friedman - @KateFriedman-NOAA / kate.friedman@noaa.gov
Walter Kolczynski - @WalterKolczynski-NOAA / walter.kolczynski@noaa.gov
1.2. Where to do development?
In authoritative (main) repository:
Work for upcoming implementation (who: members of global-workflow-developers team)
Major new features or port work (who: generally code managers and/or members of global-workflow-developers team)
In a fork:
Everything and everyone else
How do I fork this repository? See the following GitHub documentation on forking repos: https://help.github.com/en/github/getting-started-with-github/fork-a-repo
1.3. Protected branches
The following global-workflow branches are protected by the code management team:
develop (HEAD)
dev/gfs.v16 (kept aligned with current production, as well as ingests bug fixes and updates between release branches)
These protected branches require the following to accept changes:
a pull request with at least 1 reviewer sign-off
a code manager to perform the commit
Other authoritative repository branches may also be protected at the request of members of the global-workflow-developers team.
1.4. How to get changes into develop (HEAD) branch
The following steps should be followed in order to make changes to the develop branch of global-workflow. Communication with the code managers throughout the process is encouraged.
Issue - Open issue to document changes. Reference this issue in commits to your branches (e.g.
git commit -m "Issue #23 - blah changes for what-not code"
) Click here to open a new global-workflow issue.GitFlow - Follow GitFlow procedures for development (branch names, forking vs branching, etc.). Read more here about GitFlow at EMC.
To fork or not to fork? - If not working within authoritative repository create a fork of the authoritative repository. Read more here about forking in GitHub.
Branch - Create branch in either authoritative repository or fork of authoritative repository. See the Where to do development? section for how to determine where. Follow GitFlow conventions when creating branch.
Development - Perform and test changes in branch. Document work in issue and mention issue number in commit messages to link your work to the issue. See Commit Messages section below. Depending on changes the code manager may request or perform additional pre-commit tests.
Pull request - When ready to merge changes back to develop branch, the lead developer should initiate a pull request (PR) of your branch (either fork or not) into the develop branch. Read here about pull requests in GitHub. Provide some information about the PR in the proper field, add at least one reviewer to the PR and assign the PR to a code manager.
Complete - When review and testing is complete the code manager will complete the pull request and subsequent merge/commit.
Cleanup - When complete the lead developer should delete the branch and close the issue. “Closing keywords” can be used in the PR to automatically close associated issues.
1.5. Development Tools
See the /test
folder in global-workflow for available development and testing tools.
1.5.1. Comparison Tools
There are several scripts to compare output between two experiments (e.g. control and test). See scripts under /test
folder and read README there for information on how to use them.
1.6. Code standards
All scripts should be in either bash or python 3.
We have adopted the Google style guide for shell scripts and PEP-8 for python. Python code should additionally have docstrings following numpy style.
All new code after 2022 Sep 1 will be required to meet these standards. We will slowly be updating existing scripts to comply with the standards. We are also in the process of adding GitHub actions to automatically lint code submitted for PRs.
1.7. Pull request standards
Pull requests should follow the pre-filled template provided when you open the PR. PR titles and descriptions become the commit message when the PR is squashed and merged, so we ask that they follow best practices for commit messages:
Limit the subject line (PR title) to 50 characters
Capitalize the subject line
Do not end the subject line with a period
Use the imperative mood in the subject line
Use the body to explain what and why vs. how
The final line of the commit message should include tags to relevant issues (e.g.
Refs: #217, #300
)
This list is a modified version of the one provided at https://chris.beams.io/posts/git-commit/ with a couple removed that are not relevant to GitHub PRs. That source also provides the motivation for making sure we have good commit messages.
Here is the example commit message from the article linked above; it includes descriptions of what would be in each part of the commit message for guidance:
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
A detailed commit message is very useful for documenting changes.