-
Notifications
You must be signed in to change notification settings - Fork 146
Home
Welcome to the Data Assimilation Research Testbed (DART) wiki!
We are experimenting with efforts to engage the community in the latest DART activity. Please suggest or contribute any content you think would benefit the DART community at large!
Please see the sidebar for topics we felt might be of interest. Also feel free to contact us at [email protected] for more information regarding this wiki or DART development in general.
In this page we discuss the Git best practices and procedures for developing the Data Assimilation Research Testbed (DART). This page is intended for both internal as well as external developers who would like to contribute to DART. For more information on DART, see https://dart.ucar.edu/pages/Getting_Started.html, and for general purpose information on Git, see https://en.wikipedia.org/wiki/Git
Git is an industry-standard platform for source control, code revision, and making it easier for a team to develop software. Git is not a substitute for effective communication, good code design, or following development practices. This document is intended to bridge the gap between the tools provided by Git and Github.com and effectively using those tools in "people-space."
This section gives a list of things you should do as well as things you should not do (don'ts).
DO:
- Be in contact with the DART development team ([email protected]) to make sure you are not duplicating effort, the basic code ideas/locations seem reasonable, etc.
- Fork DART or DART_Development (detailed below)
- Make a feature branch off of your fork (detailed below)
- Keep your additions as modular and self-contained as possible
- Test your code before committing it
- Make a pull request to merge your changes
DO NOT:
- Try to commit directly onto the master branch
- Combine several "features" onto a single branch
- Let your code get far out-of-date with the master (merging can be difficult)
- Commit code that does not compile ("commit" means it compiles)
- Put your initials around individual comments/blocks of code/etc. The git blame command lets everyone know exactly what lines were modified. Keeping the modifications as small as possible makes the merge and difference algorithms work better.
- When contributing new files: Do not commit any of the old version control keyword lines. Since GIT does not support this kind of versioning, there is no point dragging along outdated and potentially misleading information. The only exception is the 'source' keyword, which we will be using for logging purposes. Please use the following style, replacing the filename with enough of the filename to uniquely identify the file. For example:
character(len=*), parameter :: source = 'clm/model_mod.f90'
One of the advantages to using GitHub is the ability to have your own repository and graphically and visually compare your repository to some other repository. GitHub makes it easy to create your own repository on Github via a process called 'Fork'ing. Simply click the 'Fork' icon from the DART repository and GitHub will do the rest. If you do not have a GitHub account, you will be prompted to create one. GitHub has instructions for forking a repository on the following page: https://help.github.com/en/github/getting-started-with-github/fork-a-repo.
Great - so now you have a repository on GitHub. Time to get a repository on a machine. That process is called 'cloning', and GitHub provides a button for that. There are two choices for the protocol to use to let GitHub and you machine communicate: HTTP or SSH. Either one will work, if you go through the setup process to generate SSH keys (again, GitHub has instructions for that), you will not need to type your GitHub password very often (you still need it to log in, change your personal settings, etc.) The GitHub tutorial for cloning is: https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository
Experience has shown that it is best to keep your development on a branch other_than 'master'. A 'feature branch'. Periodically, it will probably be necessary to merge changes from the master branch back onto the feature branch. There is nothing special about a feature branch other than how it is used. There is nothing wrong with having multiple feature branches - in fact, quite the opposite. Since every repository has all the branches, making a new branch (from master, in this example) and automatically checking it out - is simple:
git checkout -b <new_branch> master
The only complication is if you have uncommitted changes on your current branch. There is a possibility that checking out a new branch will cause a conflict or try to replace an unversioned file with a versioned one of the same name. Git is understandably cautious in these cases and will not perform the task and issue a warning with instructions on how to fix the situation.
We agreed to use the names origin and upstream the same way most other github users do. We assume you have made a personal fork (the origin) of the DART repository (the upstream repository), and then cloned the origin. The source of the clone is automatically added as the origin, but it is useful to also have a way to compare or pull from the upstream repository. You will likely need to add a remote, both are shown for reference. Note that the syntax used above requires setting up SSH keys on GitHub, which greatly streamlines the day-to-day workflow by relieving the requirement to incessantly type passwords.
git remote add origin [email protected]:your_github_user_name/DART
git remote add upstream [email protected]:NCAR/DART
Contributing your efforts to DART is best done through the GitHub Pull Request (PR) mechanism. Since your GitHub DART repository was Forked from the NCAR/DART GitHub repository, this is a rather simple process. GitHub has the following detailed help page on Pull Requests: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests
Essentially, the GitHub interface allows you to offer up the changes on your feature branch to the group that administers the NCAR/DART repository. The PR destination branch should be the NCAR/DART branch you used as the starting point for your feature branch. The PR interface allows people to make specific comments on individual lines of code and provide feedback on the proposed changes or additions. You can make changes on your local repository, test them, and push those changes to your same branch on GitHub and the same PR is updated. The reviewers are automatically notified. You can use the PR interface to 'Resolve' individual comments (please add a comment explaining why you are Resolving the comment!). The reviewers can also download a copy of your feature branch and test it.
What has happened so far is that there are some changes that the DART development team would like to make (implementing DART coding practices, etc) that are too trivial to require before accepting the PR. In these cases, the DAReS team can actually make the changes on their downloaded copy and merge and close the PR. Consequently, there may be minor differences between your original PR and what is actually merged. To keep things consistent, you should update your branch to remain up-to-date with the NCAR/DART branch.
See the Wiki: https://github.com/NCAR/DART/wiki/GIT-Workflow-Tips-&-Tricks