Branching Model

Frieder Bluemle edited this page Feb 15, 2016 · 22 revisions

This is the branching model for Bumblebee development. Please read this. (It will be summarized here in function of our needs)

master

This branch is the most stable one, from here are branching off every other branches.

hotfix

May branch off from: master
Must merge back into: master, develop
Branch naming convention: hotfix-*

Such branches are intended to fix as fast as possible issues in the master branch.

release

May branch off from: develop
Must merge back into: master, develop
Branch naming convention: release-*

Such branches are for testing new versions before releasing them. The RELEASE_NOTES should be added at this step, Makefile.am has to be updated to include the correct ones, and configure.ac has to be updated for the new version number. We may create a beta package building bumblebee from here.

develop

Permanent branch. Initially branched off from master.

This is the branch that receive all the new features that are implemented. The dev package is building from this branch.

common-feature

May branch off from: develop
Must merge back into: develop
Branch naming convention: common-feature_name

Such branches contain new features for which implementation is in progress and that are common for all distros.


How to work with branches

Creating a new branch

Create a new branch

To create a new branch, do this:

git branch <new_branch_name> <branch_you_are_branching_off>

Push it on a remote server (your's, Bumblebee-Project one, ...)

To put the branch on a remote server, you must do this:

git push <remote> <local_branch_name>:<remote_branch_name> # Replace remote by the server remote name (origin, upstream, ...)

It's advised to give the same name.

Make a local copy of a remote branch

If you want to do a local copy of a remote branch someone added, you should do this:

git branch --track <local_branch_name> <remote>/<remote_branch_name>

It's advised to give the same name.

Switch branches

To switch between branches, you have to make sure that the working directory is clean by doing git status.

Then, just do git checkout <branch_name> to switch to the branch called "branch_name".

If the working directory isn't clean, and if you don't want to commit the changes you've made in this branch right now, there is a solution.

Before switching, run git stash.

Then switch, do your work on the other branch.

When you will be back to the first one, just do git stash apply to get your changes back.

Merge a branch

The below procedure is talking about merging globally.

First, switch to the branch to merge in.

Then, do:

git merge --no-ff <branch_to_merge>

And you may also want to push the change:

git push <remote> <branch_you_merged_in>

Procedure to merge into a main branch (master/develop)

In order to make a clean merge back into these main branches is preferable to do some extra steps:

First switch to the feature branch you want to merge back:

git checkout <feature-branch>

Then merge the main branch (develop/master) into the feature branch:

git merge --no-ff <main-branch>

Resolve any conflicts, test the code and then merge the branch back into the main:

git checkout <main-branch>
git merge --no-ff <feature-branch>

This way all conflicts can be resolved and the test are made in the feature branch keeping the main branch as clean as possible.

Tagging a release

When a release is ready it should be merged into branch master and be tagged immediately. You need to sign that tag with your GPG key so you must provide the ID in the .git/config file or pass it as an argument with the -u option (note that if you specify -u you don't need to specify -s). Currently Lekensteyn and Samsagax are the ones who signed the versions. When the key is ready, run the following command:

git tag -s <tagname>

The is always in the form vX.Y.Z where 'X', 'Y' and 'Z' are the version numbers. You will need to provide a changelog. Make it as descriptive as possible and introducing references to issues closed.

After creating the tag you need to create the tarball. To do so run the following commands:

autoreconf -fi
./configure --prefix=/usr --sysconfdir=/etc
make dist

After that you can upload the tarball to bumblebee-project.org (user bumblebee), using either scp or sftp.

Delete a local copy of a branch

When a branch is merged back and deleted on the server, if you were having a local copy of this branch, you're still having it. To remove it do:

git branch -r -d <remote>/<branch_to_delete>

In case of error (it can happen with problem on the remote), just run:

git branch -d <branch_to_delete>

Delete a branch without merging and discard all changes in it

If a branch appears to be a bad idea for a reason or another, you may want to delete it and discard all its changes. In order to do that, just enter:

git branch -D <branch_to_completely_remove>

Delete a branch on a remote

Please let ArchangeGabriel do this on the team repo (it is here mostly for his deficient memory).

git push <remote> :heads/<branch_to_delete>