We use a centralized rebase workflow for our "master" branch combined with feature branches. Each commit destined for master is first pushed to a feature branch and then fast-forward-merged from there to master. Larger features are developed incrementally, split into small pieces with individual feature branches being fast-forward-merged into master.
No local changes should be made to the local "master" branch: all changes should occur on a feature branch. For simplicity, pulls and pushes are done directly on the feature branch, so normally the local "master" branch is rarely used.
Clone the repository, either via ssh if you've set up ssh keys in your Github profile:
Or via https:
Before doing anything on a fresh clone, run the development setup script (commands for updating and for code reviews depend on it):
Additionally, make sure that your full name is listed in the
Name field at https://github.com/settings/profile and that a legitimate email address that represents you is set as your primary Github address at https://github.com/settings/emails. Those two fields will be used for the author line for pull requests when they are squash-and-merged into master. You must also uncheck
Keep my email address private in the email settings page.
Small features or bug fixes, i.e., those that will become a single commit in the master branch, use "feature branches".
Ensure origin is up to date:
Then create a new branch for the feature or bug fix, called a "feature" branch. Replace "NNNN" with the issue number and "myfeature" with a name of your choice following the naming conventions below:
Now perform your work in the feature branch, committing locally.
For a small feature or bug fix, the name should start with the issue number prefixed by
i, followed by a dash, followed by a short description. For example,
i2157-reattach. If there is no filed issue, use the
iX- prefix. For example,
iX-fix-readme-typo. If there will be multiple changes for an issue, create a different branch for each subsequent change, prefixing them with the same naming convention (i.e.
i followed by issue number). For example:
i2172-adding-wrappers, etc. Note also the change naming conventions in such a case.
Although often a feature branch is short-lived, sometimes experimental work is not able to be finished immediately and there is value in sharing the code so that others can pick up on it. This is the logic behind using descriptive names for feature branches.
For an experimental branch (see below), the name should start with
experimental-. For example,
git pullall alias runs a script that does the right type of update depending on whether you're in a feature branch that has not yet been pushed to the Github repository (where we want a rebase) or in a branch that has already been pushed (where we want to rebase from the remote feature branch and merge from the upstream master).
Thus, to update your current feature branch with the latest content in both the upstream master and in the remote feature branch, if it exists, simply execute:
After you've shared the branch for review, it is fine to not bother to update to master prior to the final merge, relying on Github's Update Branch button at the time of the merge. If you do need to update from master for some local testing, it's best to use a merge rather than a rebase to avoid losing history in the pull request, and
git pullall will make sure that a merge is used. Don't worry about merge commits in feature branches: they'll be removed in the final squash-and-fast-forward-merge step onto master.
If you've pressed the Github button to update the feature branch with changes from master, and you now want to add a commit to your local branch (or have already added one), you want to pull the Github-added commit from the feature branch rather than master as a rebase. As mentioned,
git pullall does that for you (along with updating from master).
Code reviews are requested by pushing the feature branch to Github and then creating a pull request onto master. See code review details here. Merges to master occur only via pull request.
Once your changes have been merged into master, you can delete your feature branch with these commands (substituting your branch's name for "feature"):
You can check out an existing feature branch
This is equivalent to:
If you want to split off the first commit or two from a feature branch and you issue a command like this:
tocheckin branch will not be a tracking branch. You'll need to issue this command:
If you've run the development setup script, you can run both commands at once with:
For larger features or projects which will end up containing many commits, the workflow is unchanged. Work proceeds incrementally, with each small piece being committed to master using a feature branch and pull request.
For experimental, quick-and-dirty work, especially where the work was already finished privately or where for time constraints and other reasons the regular development process is not suitable, we support experimental branches. The idea is to promote sharing of academic prototypes and other projects, with the goal of sharing the ideas immediately and making it more likely that the ideas will be eventually integrated into master, by separating the initial sharing from the later clean up and incremental code review. As described above, experimental branch names start with
Please note that like other contributions, code contributed to an experimental branch is offered under the terms of our license.
Some potentially useful aliases that are not in the development setup script include the common tasks of looking at the log of changes versus the remote master:
And looking at the full diff versus the remote master:
Our workflow uses fast-forward-merge and rebase when merging into the master branch. We do not want any merge commits on the master branch: we want a nice clean line of history. Merge commits on feature branches are fine as they will disappear upon merging into master.