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.
...
When creating a branch, multiple levels of namespacing are allowed. In ACME, a branch should be namespaced first by github user in charge of the branch. Similarly, directories contained within tools and scripts can be used to namespace within those directories. This pattern continues into each subdirectory. For example, a branch that is implementing a new parameterization within cam would be named:
joeuser/cam/new-parameterization
And a branch that is modifying the HOMME dynamics would be:
janeuser/homme/new-se-feature
Branch names should be as long as needed to clearly convey what the developer is working on, but they shouldn’t be overly long and descriptive. The following example is a branch name that is too long:
joeuser/cam/this-is-my-awesome-new-feature-that-does-something-cool-and-we-might-not-use-in-the-future
...
NOTE:
Creating a new branch will not change the current branch that is being worked on in the current working directory.
Changing Branches
Because the git branch command does not modify the current branch in the current working directory, new commits will not be made to the new branch. In order to change the branch that is being worked on, the git checkout command is used. For example:
...
NOTE:
Creating a new branch and swapping to it can be done in a single command via:
git checkout -b github-username/component/feature master
Utilizing the repository history
...
Seeing as all of the ACME developers are stewards of the repository history, it would be useful for developers to understand how to make use of the history they are maintaining.
The The most useful command for making use of the history is the git log command. This command has an abundance of optional arguments and this second can be used to get an idea of what you can do with git log.
The basic usage of this command gives the equivalent of an svn log. Where you get a list of all commits and their commit messages. By default, git log only shows commits that are reachable in the history of the HEAD. Optional arguments can be used to look at different (or all) branches.
One extremely useful version of git log gives a command line graph of the history.
git log --oneline --graph --decorate
git log can also only show local branches that match a certain naming convention. i.e.
...
git log --branches=*pattern*
The --branches option can be replaced with --remotes to only show remote tracking branches that match a pattern.
A specific commit has three pieces of information. The first is the commit’s tree (i.e. the files and directories contained in the commit), the second is the commit’s message (the commit message issued when creating the commit), and the third is a list of the commit’s parents. There can be multiple parents for a single commit, which would imply the commit was a merge commit. Git stores the order of the parents, with the first parent always being the commit the merge was initiated from. This is useful to note, because within our workflow first parent commits on master should always be merge commits bringing in features or bug fixes. git log can be used to narrow your view to only see first parent commits as well, via:
git log --first-parent
As you develop a new feature, you might migrate files from one place to another, or even rename the file. In order to have git show you all renames of a file, you can use the following command:
git log --name-only --follow -- path/to/file
Any of these options can be combined to give more flexibility to exploring the history of a git repository and make the history more useful.
Incorporating another branch on to your branch.
When developing a new feature, another developer might have created a feature you require for your work, or another developer might have made large changes to the interfaces you make use of. This section will describe how to incorporate those changes into your branch.
...
NOTE:
This action can have negative consequences and cause issues in the future, so it is important to know what you’re doing prior to doing any of these.
Cherry-pick method
...
The first option for incorporating changes from another development line into your development history is via a cherry-pick. A cherry-pick will copy individual commits (or a range of commits) from one point in history onto the HEAD of your current development line. It should be used when the number of commits your future development efforts depend on are small (order 1-10). It can be used as follows:
...
This method is the easiest to use and one of the least likely to create issues in future development, and allows the most flexible review modifications. One downside to this method, however, is that the commits that are cherry-picked will now occur twice in the history.
...
Merge Method
The second option for incorporating changes into your development history is via a merge. A merge will attempt to merge an arbitrary number of other commits (or branches) into your current branch. It can be used as follows:
...
A merge creates a fixed point in history. The merge commit fixes all history before it, which limits possibilities for cleaning up history during a code review. A merge should be avoided if at all possible, but in some cases it is necessary. If it is necessary, try to clean up all history prior to the merge before beginning the merge.
...
Rebase Method
The third and final option for incorporating changes into your development history is via a rebase. A rebase allows you to modify commits. This includes operation such as squashing, re-ordering, deleting, etc. When you create a branch, the base of the branch is the commit you branched off of. A rebase allows you to modify what the base of your branch is. The following diagram can be used to visualize a rebase:
...
This will again open an editor for a commit message to be entered.
Submitting a pull request
...
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.
...
Finally, modifying code might require introducing new commits, or editing previous commits.
Testing a feature
After a reviewer is satisfied with all parts of a pull request, both the reviewer and the developer will perform testing on the pull request. The developer may be required to point a reviewer to a specific test case or namelist that can help the reviewer test the feature. In addition to testing the feature, it is the reviewers responsibility to verify the pull request does not introduce issues related to the previous functionality of master.
This can either be performed on the branch itself, or in an integration branch. The reviewer will inform the developer where testing should take place.
Fixing bugs in a new feature
...
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
...
Working with Remote repositories
...
Git is a distributed content versioning system (DCVS). When you clone a repository, you make a local repository that is essentially a backup of whatever you cloned. When you commit, the commit only occurs in your local repository. In order to allow other people to make use of the commits you make, or to get your commits incorporated into master they need to be “pushed” to a remote.
A remote is a repository that you would like to communicate with, that is not in the local working directory. When you clone a repository, a default remote is created named “origin” that points to whatever you cloned. A remote is really just an alias to the location of another repository you either want to read or write with.
Before 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.
The push command can be used to write some commits from your local repository to a remote repository. For example:
git push <remote-name> <local-branch>:<remote-branch>
...
can be used to write a local branch to a remote branch on the remote pointed to by the name provided. An explicit example would be:
git push ACME-Climate/ACME feature:github-username/component/feature
In this case, we’re writing the branch feature to the remote origin and changing its name to core/feature.
git push is the command used when writing history to remotes. In order to read history from remotes, the git pull and git fetch commands can be used.
The git fetch command will update the local repository with the most recent history from a specific remote, without modifying any local branches in the repository. It can be used as follows:
git fetch <remote-name>
...
The git pull command is a combination of two operations. The first is a git fetch in order to update the history in the local repository of the branches that exist on the remote repository. The second is a git merge which merges the changes into the current working directory. It is only recommended to use this if you know what you’re doing. It can easily cause unexpected problems. It can be used as follows:
git pull <remote-name> <branch-name>
...
Git vs. Svn Merges
and why you don't always need to merge from master.
...