Contributing
NOTE: This CONTRIBUTING page is for software contributions. You do not need to follow the Developer's Certificate of Origin (DCO) process for commenting on documentation, such as CONTRIBUTING, About, etc. or for submitting issues.
Thanks for for your interest in using or contributing to WAVEWATCH IV (WW4) and its documentation! This page addresses the following topics.
The code manager for WW4 will only accept contributions using the Developer's Certificate of Origin 1.1 located at developercertificate.org ("DCO"). The DCO is a legally binding statement asserting that you are the creator of your contribution, or that you otherwise have the authority to distribute the contribution, and that you are intentionally making the contribution available under the WW4 licence in the LICENSE.md file.
Before submitting contributing code to this repository for the first time, you'll need to sign a Developer Certificate of Origin (DCO) (see below). To agree to the DCO, add your name and email address to the CONTRIBUTORS.md file. At a high level, adding your information to this file tells us that you have the right to submit the work you're contributing and indicates that you consent to our treating the contribution in a way consistent with the license associated with WW4 (as described in LICENSE.md).
Pseudonymous or anonymous contributions are permissible, but you must be reachable at the email address provided in the Signed-off-by line.
If your contribution is significant, you are also welcome to add your name and copyright date to the source file header,and in the CONTRIBUTORS.md file in the main directory of the repository.
U.S. Federal law prevents the government from accepting gratuitous services unless certain conditions are met. By submitting a pull request, you acknowledge that your services are offered without expectation of payment and that you expressly waive any future pay claims against the U.S. Federal government related to your contribution.
If you are a U.S. Federal government employee and use a *.mil or *.gov email address, we interpret your Signed-off-by to mean that the contribution was created in whole or in part by you and that your contribution is not subject to copyright protections.
The full text of the DCO is included below and is available online at developercertificate.org:
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.Before you can contribute to WW4, you might want to try and run the model. If you have never done that yet, please visit the Quick Start Guide, and have some fun!
Issue with WW4 code and requests for WW4 code modifications are handled through our wiki page. For details, see the GitHub discussions feature in the WW4 repository.
NOTE: at this point we expect you to have a working knowledge of Git and GitHub and their vocabulary (of course, you can always go to GitHub flow page for a refresher). This is NOT a Git or GitHub tutorial!
NOTE: This needs to be synchronized with the report text, and we need to add pages on standards.
If you want to contribute code to WW4, it is important to understand and follow the structure and workflow in this repository (section 2 below). Moreover, Git and GitHub represent a distributed repository approach, where you do not work in the authoritative repository (https://github.com/NOAA-EMC/WW4), but in a copy of this repository that you own. The interactions between your local repository and the authoritative repository is the second key aspect driving contributions to WW4 (section 3 below).
WWW4 uses GitFlow to manage branches in its repository. The following description of GitFlow consists of selective copies from an internal NOAA document entitled “Code Management of Repositories under EMC management using GitFlow“ with minor edits only. Note that in GitHub, Gitflow is now generally referred to as flow or GitHub flow.
Gitflow originated from a blog that was written by Vincent Driessen in 2010. Gitflow is a philosophy for managing branches in a development repository. It is clean and straightforward and has been adopted as the standard for code management all over the world. The figure below is reproduced from Vincent’s blog. This is not a new idea and many code development communities are well aware of this approach. While the main idea has been for getting codes released for the public, the same principles apply for getting codes ready for transition to operations. At its heart the concept of Gitflow is a series of branches with strict functions.
develop: This is the main development trunk. All code development uses this branch for syncing and coordinating. This is different from the main (defined below) in very definite ways. Updates to develop can only be done by the code manager after the code has been approved by a team of assigned reviewers. Name we use: develop.
main: (the term master is used in the original blog, but the term main is more consistent with GitHub nomenclature and is used for WW4). This is the branch that is the mature part of the development. It is the one that will be either released to the public or will be put in operations. It is updated much less frequently than the develop branch. It follows a strict testing protocol process before it is updated. Updates to main can only be done by the code manager after all tests have been completed and reviewed by assigned reviewers. Name we use: main.
feature: These are the branches where developers work. They are always created off of the develop branch to develop new ideas and capabilities. Name we prefer: start name with FT.
bugfix: (Not part of the original blog.) This is a bugfix branch that is only created from develop. This is to address bug fixes to the development branch as such bugs are encountered. Name we prefer: start name with BF.
release: This branch is created once the development reaches a certain stage that you are ready to “freeze” the code for a) release to the community and/or b) transition to operations. A release branch is where detailed exhaustive testing happens and bugs are fixed. This branch keeps getting merged back to develop to ensure that bug fixes get back to the main development trunk. Name we prefer: start name with RL.
hotfix: This is a bugfix branch that is only created from main. This is to address immediate fixes that were overlooked in the testing process (it will happen, rest assured). Name we prefer: start name with HF.
Practical examples of how this works including a graphics representation of the workflow can be found in the original blog
Note again that the GitFlow approach described here is operating within a single repository. As the distributed nature of Git implies that you will work in your own local repository, interactions between repositories are also critical. The following subsections steps and procedures in working with multiple repositories and contributing your work to the community.
-
Step 1: Create a GitHub Account
- You will need a GitHub account to contribute to WW4. If you do not have one yet, create a GitHub account by following the instructions outlined on https://github.com. Note that you do not need an account if you are only downloading the code in order to run it.
-
Step 2: Fork the WW4 Repo
- You are required to work from a
forkof a trusted repository, rather than itsclone. You can only create forks using the GitHub web interface. - On
github.comnavigate tohttps://github.com/NOAA-EMC/WW4. - Locate and click the
forkicon on the upper right-hand corner of the WW4 GitHub page.
- You are required to work from a
-
Step 3: Clone your fork to a local copy
- You will work on WW4 on the computer of your choice and not directly in GitHub. To do this, you create a 'clone' on your local machine by typing the following command in the directory under which you want the clone to reside.
git clone https://github.com/<your username>/WW4- If your machine (or you) require secure communications with GitHub, set up
sshcomunication in general, and replacehttpswithsshin the command above.
-
Step 3b: _Placeholder for copying large data files into the clone
-
Step 4: Add
Remotesto enable management across repositories Remotes are GitHub repositories that are linked to your local copy. A first remoteoriginis automatically created when you clone a repository, linking your local copy to the fork you created in your GitHub account. You can keep your local copy synced with your fork and vice-versa by simply using commands such asgit pullto sync the local copy with the fork, orgit pushthe other way around. That is enabled by creating a remote link within your local copy that points to theupstreamrepositorygit remote add upstream https://github.com/NOAA-EMC/WW4
Development work is done in feature or bugfix branches created from the develop branch in your local cloned directory.
We expect you to follow the following rules of engagement here:
- Create an issue with the planned feature update or reporting the bug fix being worked on.
- Create one
featureorbugfixbranch for every single feature or single bugfix you will be working on. Do not bundle all features or bugfixes in a single branch, as this creates a situation where undeveloped features will get in the way of reintegrating mature work,- We are so adamant about this that pull requests with more than one feature per branch will be rfequired to split their development into multiple pull requests.
While doing your development, it is good practice to sync your local copy to the upstream remote regularly, as allowing conflicts in this process to accumulate tends to lead to exponentially more work to sort them out. This is how the syncing is done:
-
Change to the active development branch
git checkout develop -
Copy over changes to upstream repo
git fetch upstream -
Merge changes to your local repo
git merge upstream/develop -
Push changes to your GitHub fork
git push
Likewise, you want to keep your main branch on your local clone up to date with the same process, starting with git checkout main.
Finally you want to kep your fork on GitHub up to date with the authoratative repository. This is done by navigating to your fork on GitHub and clicking the sync button in the upper right hand side of the web interface.
Once you have created your feature or bugfix branch as described above, a typical development cycle looks as follows. Always make sure you work from the directories associated with the branch you are working in (in your local cloned repository).
-
Work, Work , Work ….
-
Make sure you incorporate Coding Standards and Documentation Standards, and set up the appropriate Automated Testing for your contributions.
-
Regularly execute the appropriate Automated Testing .
-
-
Frequently commit your changes to the branch.
-
Check changes made with
git status -
Add files indicated by
status
git add <some files> -
Commit changes locally in your
clonedrepository- Use a commit message in the form "<
branch name>: [description of changes]":
git commit -m "<branch name>: [description of changes and files affected]"
- Use a commit message in the form "<
-
-
Push changes to your GitHub fork
git push origin <branch name>
Once your project reaches maturity, reintegration in the main WW4 repository makes it available to everyone. This is done using a Pull Request.
Pull requests are proposed changes to a repository submitted by a user and accepted or rejected by the main code managers. Before you submit a pull request, make sure to fully fill out the template we provide. When you get to that point, follow the well-established in GitHub guidelines
-
Using your browser, navigate to the original repository you created your fork from.
- To the right of the Branch menu, click New pull request.
-
On the Compare page, click the highlighted link
compare across forks. -
Confirm that the base fork is the repository you'd like to merge changes into.
- Use the base branch drop-down menu to select the branch of the upstream repository you'd like to merge changes into.
-
Use the head fork drop-down menu to select your fork,
- then use the compare branch drop-down menu to select the branch you made your changes in.
-
Type a title and description for your pull request. Follow the PR template instructions to provide the necessary details.
-
If you do not want to allow anyone with push access to the upstream repository to make changes to your PR, unselect Allow edits from maintainers.
-
To create a pull request that is ready for review, click Create Pull Request.
- To create a draft pull request, use the drop-down and select Create Draft Pull Request, then click Draft Pull Request.
For more information about draft pull requests, see About pull requests.
After your changes have been merged into the develop branch, it can be helpful to delete the branch with the feature and do any other clean-up in your fork. Now, you can restart the development cycle with new branches created from an up-to-date develop branch of the authoritative repository.
