-
Notifications
You must be signed in to change notification settings - Fork 0
Typical project workflow and setup
This document will describe the typical steps for beginning a new project in the MPAS git repository.
To begin, please review this document which describes the high level branching strategy for this repository.
It's very important that developers adhere to this branching strategy, as this repository will eventually be used for releases.
In order to begin a new project, the first step is to create a fork. To create a fork, simply visit the github page for the repository of interest (e.g. MPAS).
After a fork has been created, a there will be a new repository in the list of repositories both for the MPAS-Dev organization and your personal user account. If you visit this page, it will give you the address for the repository. For example, [email protected]:MPAS-Dev/MPAS.git. Once you have a fork, MPAS-Dev will be replaced with your username, for example [email protected]:douglasjacobsen/MPAS.git.
Once you have the fork created, and the address for the specific for (we'll use [email protected]:douglasjacobsen/MPAS.git in this example)
You can checkout the fork locally with the following command
git clone [email protected]:douglasjacobsen/MPAS.git
This will create a new directory called MPAS in the current working directory. This contains the entire MPAS repository.
As per the branching strategy at the beginning of this page, master is reserved to releases. Develop is the name for the main development branch. New "feature branches" should be created from develop. Before creating a branch, you should switch to the develop branch. This is accomplished through the following command (from inside the local checkout of the repository)
git checkout develop
After develop is checked out, a new branch can be created. It's important to create descriptive and useful branch names, so when other developers need to find related projects they can do so easily. For example, if you were working on a project to implement a new history attribute in output files, this would largely affect the shared framework. Because of this, a good name for the branch would be
framework/history_attribute
This way, other developers can search for branches with the name framework/ to see which branches affect framework. To create this example branch, one simply has to do the following:
git checkout -b framework/history_attribute
This both creates the branch, and switches to it. Alternatively these two steps can be separated be using the following two commands:
git branch framework/history_attribute
git checkout framework/history_attribute
Once some work has been done in the branch, or a developer wants to share the branch, it needs to be pushed to their fork. When git clone was used, a remote repository was setup called origin that points to the specific repository (or fork) that it was cloned from. A clone of a repository can have as many remotes as a developer wants, and these remotes can be used to share code between different forks and different developers.
In order to push a branch to a remote, the developer needs to have push access to that repository. Every developer has push access to their own fork. Pushing is as simple as:
git push origin framework/history_attribute
This creates the framework/history_attribute branch on the remote origin. In order to delete a branch on a remote, one simply has to:
git push origin :framework/history_attribute
Pulling is a method of grabbing changes from another remote into your local clone. A pull can be issued similarly to push:
git pull origin framework/history_attribute
A pull will modify your working directory, which might not be what you want. Behind the scenes, a pull performs two actions. First, a fetch and second, a merge.
Alternatively to pulling, one can fetch a remote branch into their local clone as in:
git fetch origin framework/history_attribute
If the current working directory has changes on the framework/history_attribute branch two ways of combining the changes with the fetched changes are available. The first is a merge, while the second is a rebase. In this specific example, a rebase is more likely what you are looking for.
Although the rebase command is intimidating, the concept is rather simple. When the project was started, and several changes were created, the base of the changes was the point where the branch started. In a rebase, the changes between the base of the branch, and the HEAD (or tip) of the branch are set aside, and overlaid on the HEAD (or tip) of another branch. Doing this allows the history of a branch to remain linear.
For example, if a remote named test has updates to framework/history_attribute that I wanted to combine with some local modifications to framework/history_attribute, I would first fetch the changes:
git fetch test framework/history_attribute
And second, rebase my changes onto the remote branch:
git rebase test/framework/history_attribute
This will overlay my local changes onto test's version of framework/history_attribute.
Once a branch is complete, it can be merged into another branch. This can be performed by issuing:
git merge framework/history_attribute
This command should be issued from the branch you want to merge in to. For example, if framework/history_attribute needs to be merged into the develop branch, you can issue:
git checkout develop
git merge framework/history_attribute
The git merge command can take any number of branches as input to merge, and will attempt to merge them together as cleanly as possible.
After a project is complete, the branches need to be deleted. The deletion of a remote branch was covered earlier, so this section will only cover the deletion of a local branch. To delete a local branch, the following command can be used:
git branch -d framework/history_attribute
This will only remote the branch if it has been merged. If it has not been merged, and you are sure you want to delete it the following command can be used:
git branch -D framework/history_attribute