BranchingStrategy

From crowdresearch
Revision as of 13:17, 30 May 2015 by Karanrajpal (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Forking

The first thing you need to do is go on to https://github.com/crowdresearch/crowdsource-platform, and click on fork.

A fork is basically a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project. Once you are sure of your changes, you can raise a pull request to merge your changes to the original project.

When you have forked the project, you will find it in your github account.

Cloning

Now, you want to get this forked repository onto your machine so you can start making changes to the code. Cloning refers to getting the code onto your machine. You can clone a repository by typing this into your command line :

git clone https://github.com/<your-username-here>/crowdsource-platform

Setting the upstream on your cloned repository

Once the cloning has been done, you need to tell git what the upstream is, that is, what have you forked from. You need to enter the directory by typing

cd crowdsource-platform
git remote add upstream https://github.com/crowdresearch/crowdsource-platform.git

Branching

When you want to add a new feature or fix a bug—no matter how big or how small—you create a new branch to encapsulate your changes. This makes sure that unstable code is never committed to the main code base, and it gives you the chance to clean up before merging it into the main branch. Type in
git branch
to figure out what branch you’re currently working on.

Now when you are starting to code a new feature, you should create a branch for it. You need to branch out from develop2.

git checkout develop2
git checkout -b feature-branch-name

This switches you to the develop2 branch if you are not already on it and then creates a new branch from the develop2 branch. The new feature branch right now is a copy of develop2. Remember to always name your branch as per the feature you are working on, and not your name.

Committing

Now, make your changes. After you're done with your changes, you need to commit them to git.

git status

This will show you a list of all the changes on your local system. Add only the files you want to push, ie the files you have changed, and not everything.

git add file1 file2 path/to/file3 file4

After adding all the files you need to, you can double check it by running git status again. Next, add a commit message using

git commit -m "The commit message describing the change"

Fetching, Merging and Pushing

Remember, these changes are in your local machine. They haven’t been uploaded to the forked repo in your github account. You need to push your local changes onto that. Before you push the changes, you need to make sure that you pull the new code from the main repository, because new changes might have been added by others while making your local changes.

So, type in
git fetch upstream

This fetches the new changes from the main repository onto your local machine (fetching does not display the new changes in code yet. For that, you need to merge). To merge the changes from the upstream develop2 onto you develop2, you need to make sure that you are in the develop branch before you merge.

git checkout develop2
git merge upstream/develop2

Now, your develop2 branch is up-to date with the upstream repository's develop2. Next, let's merge the updated develop2 code into the feature branch.

git checkout feature-branch-name 
git merge develop2 

Running git merge develop2 within your feature branch copies the updated develop2 code changes into the feature branch. At this point, you may have some conflicts. Please refer to resolving conflicts. IF there are conflicts, and you have finished resolving the conflicts, you'll need to manually make another commit using git commit -m "Merge conflicts resolved" Next, push the code to your fork on Github.

git push origin feature-branch-name

Remember, upstream is : https://github.com/crowdresearch/crowdsource-platform, and origin is : https://github.com/<your-username>/crowdsource-platform

Creating a Tag

Once you have pushed your changes, you need to create a tag that reflects the milestone number. This makes it easier to keep track of the code across different milestones. # represents the milestone number that this contribution is part of.

 git tag milestone# 

So for the first milestone, it would be : git tag milestone1, and so on. Next, push the tag :

 git push origin milestone# 

Raising the Pull Request

After a feature has been implemented, and all commits relevant to it are done, we need to merge it to upstream (ie, the main repository). We raise a pull request by opening up our github account, and clicking on the pull-request option on the top right, as shown here :

Create PR 1.png

Next, click on the 'New Pull Request' button. You will be shown a 'Compare Changes' page. Make sure the base source is crowdresearch/crowdsource and the base is develop2 branch. The head fork should be <your-account-name>/crowdsource with compare as your feature branch name. Click on create pull request, and add a relevant title and comment. Finally, click on 'Create Pull Request', and you're good to go!

Relevant Reading

A successful Git branching model