-
Notifications
You must be signed in to change notification settings - Fork 29
Policies for GitHub and git
Commits should be for related code changes. Committed code should be self-consistent (working APIs, pass tests and regressions, and have code-documentation). The commit should be documented in the commit log. Commit log should take the form suggested by Tim Pope:
One-line summarizing the commit in <=50 characters
Detailed explanation of the commit, rationale, issues addresses, etc.
goes after a blank line (THE BLANK LINE IS VERY IMPORTANT). Also:
- It is helpful to use an ascii pseudo-formatting like
this “-” notation.
- There is no need to add user information or dates since that
information is recorded by git for you.
Yes, that one-liner is exactly 50 characters long! Your editor will
probably indicate when you exceed the 50 characters. Subsequent text
is best word-wrapped at 72 or 80 characters.
Here is a ruler:
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890
Note: as of commit 38743d189c0f73212d9d9b4e3fd546f103762c5d [Apr 6, 2014] these suggestions can be included in the default commit message by running
$ git config commit.template git_config/git_commit_template.txt
from the CVMix root directory.
| Branch Name | Description |
|---|---|
master |
Considered the canonical working branch. |
bugfix/<title_of_bugfix> |
For candidate bug fixes. |
feature/<title_of_new_feature> |
For new features in existing code. |
new_module/<title_of_new_module> |
For new physics modules. |
The master branch is reserved for the core developers to maintain the sanctioned code. Sanctioned code passes all the regression tests and represents our best understanding of what the physics should be doing.
Every mixing module has an associated regression test to ensure that updates to the library do not break existing code. Currently these tests need to be run manually (and individually), but we are looking in to options for automated testing as well as a single batch script that can be run before a pull request is made.
A prerequisite to the submission of a new CVMix module is to successfully complete the suite of regression tests already in place for existing CVMix modules. This step helps insure that the code meets a standard level of integrity and usability, and that it does not break other CVMix code already part of the repository.
When adding a new mixing module to the library, you must also provide a new regression test.
The test should be time-independent and cover as many branches through the code as possible, preferably while remaining light-weight enough to run on a single processor (single-column / time-independent is ideal, but not a strict requirement).
Data should be written out using routines in cvmix_io.F90, with the _NETCDF macro used to determine if output should be in netCDF format or plain text.
The test must also include a script for analyzing output [MNL Note: NCL is currently language of choice, but maybe that will change?]. Many tests are simply cases described in the peer-reviewed paper that originally outlined the mixing method; these tests contain NCL scripts that generate plots visually confirming the paper results. For example, many of the plots from Large, et al., (1994) can be reproduced by CVMix tests.
[MNL Note: coming soon?]
Any user has read-access to the CVMix repository. If a user/developer wishes to submit code to the CVMix project for either a bug fix, new feature or new physics module, he/she should take the following steps. From here onwards, it is assumed that the developer has a valid github account.
At the CVMix source repository, click “Fork” (top-right), This step creates a complete snap-shot of the CVMix-src repository under your account. To clone (download) the code issue:
git clone https://github.com/<user>/CVMix-src.git
where <user> should be replaced by your github username.
You have the ability to push commits to your repository.
We request that you follow the same branch names guidelines when working with your own repository.
Doing so helps the core developers follow the history of requests and code.
If you are forking the repository for purposes of submitting code (either a bugfix or new module), you can delete the fork only once a pull request has been handled.
Please do not delete the fork before that.
The sections lays out three steps to submitting code updates or any form. Branch creation, pushing code and submitting a pull request.
Contributed code is never committed directly to the master branch which requires code updates to be sanctioned and pass all necessary tests and quality control. Candidate code, whether for a bugfix, feature request or new physics module, should be committed on branches with descriptive names consistent with the branch names section. To create a branch, start from the master branch and create as follows:
$ git checkout master
$ git checkout -b <branch_type>/<title_of_code_changes>
where <branch_type> might be bugfix, feature or new_module.
Once code has been committed and tested on the branch, a pull request is required to have the code merged on to the master branch.
A bugfix is specifically a change to existing code on the master branch that fixes either a functional behavior or changes numerical results.
Bugfixes should be on branches named bugfix/<title_of_bugfix>, created using:
$ git checkout master
$ git checkout -b bugfix/<title_of_bugfix>
Commit to you local working repository with:
$ git commit
at which point you will be prompted to write out a commit log. Please follow the commit log formatting style. When committing your bug fix, be sure that the commit log message includes the following information: Version of the code on which the bugfix is implemented, system configuration including platform, compiler and library versions. Also describe how the code functions before and after the bugfix. To push your commits back up to the GitHub repository, use:
$ git push
Feature requests include answer preserving refactoring of code, answer-changing new formulations or versions of existing code, API changes (changes to arguments of routines or parameter names). As for all code submissions, feature requests should be submitted on a branch. For example, the command to create a new feature branch is:
$ git checkout master
$ git checkout -b feature/<title_of_feature>
As with bug fixes, you will then need to commit and push your changes.
[MNL Note: coming soon?]
A pull request is required to have code considered for merging onto the master branch. This step provides a mechanism for code review. If you created a branch on the main repository, a pull request is instigated through the CVmix-src GitHub page via the Pull requests side menu. If you forked the repository, you will find similar links to Pull requests in the side menu of the corresponding GitHub website.
When you have pushed your code submission branch back to your repository, navigate to that branch on github (either use the pull down menu on the front page or use the “branches” tab). On the left, besides the pull-down menu click the green icon for “Compare, review, create a pull request”. This page allows you to review your changes. When satisfied, you can click “Create Pull Request”. Use a descriptive title for the pull request. In the comment section, document the bug and pull request as completely as possible; even to the point of repeating the commit logs. Click “Send pull request” to submit the request. Your pull request will be handled by the core team who will evaluate the requests and respond to you via github.
The team of write-access developers is open to volunteers with the appropriate scientific and programming expertise to join the team and contribute time coding new physical parameterizations, reviewing code submissions, maintaining code, testing, and debugging. To join us, please post to the google groups mailing list or email us. Minimum commitments include attending a weekly telecon on Mondays at 11:30ET (Princeton time) / 9:30MT (Boulder/Los Alamos time), and a commitment to actively using/evaluating/developing CVmix in the context of an ocean model.