This document provides details on ACME development conventions and practices.
...
important -- Items colored in red mean they are important, and should not be ignored.
one time -- Items colored in green are commands to be issued once per machine.
repo once -- Items colored in orange are commands to be issued once per local repository.
...
Before communicating with remotes, you might want to add or remove remotes. In order to add and remove remotes the git remote command can be used. The two uses are as follows:
git remote add remote-name protocol:address/to/repo # Creates a remote
git remote remove remote-name # Removes a remote
In order to communicate with remotes, there are three actions. push, pull, and fetch.
...
Using the "Assignee" menu, add the name of the designated Integrator for your component. See Integrator Guide for a list. This will start the code review.
This document can be used to help with pull request related issues.
...
Below is a summary of the above sections. It will provide an ordered list of commands for a typical workflow. This will not describe why you would use these commands, or even what they do, simply a typical order for a standard project. Some items will be left out, like incorporating changes from an external project that your project is dependent on.
git clone git@github.com:ACME-Climate/ACME.git
(only need to do this once per development platform (your laptop, Mira,Titan, etc.)cd ACME
git checkout -b github-username/component/feature acme-vXX
Repeat the following until development is complete:
vim file # make changes to files, or add new files
git add new-files
git commit -a # Edit commit message, based on template
Optional: git rebase -i <commit>
Optional: Incorporate externally developed feature into your feature
Option 1: git cherry-pick <commit>
Option 2: git merge [commit] [branch]
Option 3: git rebase -i <new-base>
Perform tests as needed throughout development process, but at a minimum before you submit a pull request.
git push ACME-Climate/ACME github-username/component/feature
(push to the shared repository on github)Visit http://github.com/ACME-Climate/ACME and submit a pull request to ACME/master
Reference Material
This section will be used to house additional information for people who are interested. It will attempt to clarify some of the comments made in the development reference by expanding a bit more on them. Developers can safely ignore this content, it's only provided for educational purposes.
Git vs. Svn Merges
A lot of the time, people were hear claims like "Git is better at branching and merging than svn", without explaining why this is true. The reason this is true is not necessarily that difficult to explain, it really comes down to the graph structure git uses to store history. Below there will be additional references that will go into more depth about this topic for people to read if they are interested, but an overall summary will be provided here.
One of the main differences between git and svn is how history and branches are stored. In svn branches are virtual directories (i.e. svn copy ^/trunk branch_name) and the history is stored as a stack of revisions (providing the monotonically increasing revision number). The problem with this, is that a branch isn't actually a branch. It doesn't contain the information about where it was created from or what has been "merged" into it. The same is true when a branch is merged back into trunk; there isn't a clear historical description of what has already been integrated into trunk. (NOTE: svn has put some effort into improving their branching and merging capabilities, but they are still not up-to-par with DVCS tools)
However, in git the history is stored as a Directed Acyclic Graph (DAG), and branches are first-class citizens. The DAG structure allows any commit to determine which other commits it includes changes from (or which commits have been integrated into it). Using this history structure, git is able to ignore changes from commits that have already been integrated, reducing the number of merge conflicts that occur when bringing in a large set of changes.
NOTE: While git is better at handing merges and branches, do not expect that you will never encounter a merge conflict. Merge conflicts still exists, and have to be dealt with. No version control tool will be able to automatically resolve a conflict when two people change the same line of code.
Additional References
http://stackoverflow.com/a/2692999
http://stackoverflow.com/questions/2475831/merging-hg-git-vs-svn/2477089#2477089