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.
...
Within this diagram, blue dots have associated feature branches that are omitted for the sake of readability. However, each of them followed the same development cycle as the feature that is being focused on in the diagram. Also, red commits are made to next. Both next and master should only be modified by integrators or gatekeepers.
Basic Development
Creating a new branch: new feature
New projects should be carried out on a branch. New projects include the addition of a new feature (github-username/component/feature) or fixing a bug (github-username/component/bug-fix).
When created a branch, please name it based on guidelines contained in Branch, Tag, and Version name conventions.
...
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. Next comes the main component the feature is being developed for. Finally, a description of the new development. For example, a branch that is implementing a new parameterization within cam would be named:
...
The following commands can be used to create these the feature branches:
feature branch: git branch github-username/component/feature acme-vXX
bug fix branch: git branch github-username/component/bug-fix commit-with-bug
...
The above command assumes you are on the head of the master branch and that is where you want to start the new development.
If you want to start development from a specific tag, include the tag name as an additional argument.
git branch github-username/component/feature v1.0
When creating a new feature branch, best practice suggests you should branch from a tested version of the code
...
. HOWEVER, while the model is in "version 0" mode, always start development from the HEAD of master.
Creating a new branch: bug fix
Starting a branch to fix a bug is very similar but there is an additional argument.
git branch github-username/component/bug-fix commit-with-bug
The last argument is the hash of the commit that first introduced the bug. If that was a tagged version, you can use the tag name as for the feature branch above. Bug fixes are typically never started from the HEAD of master.
Advanced developers can branch off of alternate places if they know what they are doing.
...
This will again open an editor for a commit message to be entered.
Advanced: 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.
...
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 and the process of moving this feature to master.
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
...
Additional Topics
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.
...
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.
...