-
Notifications
You must be signed in to change notification settings - Fork 150
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
See the Wiki: https://github.com/NCAR/DART/wiki/GIT-Workflow-Tips-&-Tricks