Hg WorkFlow

Introduction

Nowadays, even the experienced developers find it difficult when a project is handled by more than one developers in terms of branching. Developers just randomly commit, push and pull their code hoping that it would work fine. But in many cases a single commit may break down the entire structure of the repository. When a new developer comes into the team the real problems start. Even the developer who was doing the code may not know at what point he can get a stable code, at what part a particular feature was implemented etc. This led to the rise of various work flows. 

The workflow which I am explaining below is for developers who are using mercurial version control.

HgFlow

In Hg flow there are only 5 branches as;

• Develop
• Default
• Feature
• Release
• Hotfix

First of all we have to initialise our repository with this work flow. Before initializing the repository will look like as in figure below in sourcetree(client app for version control).

 There is only a single branch which is default as you can see on the left side.

 There is an extension in source tree for initializing and operating hgflow on the tool bar(see above image). Once we click on hg flow and click OK the repository will get initialized  with hgflow. Two branches get initialized which is the develop branch and default branch.See below images to see the prompt on clicking hgflow and the pop up before initializing hgflow.

 So now your repository has been initialized with hgflow. On left side you can now see two branches namely develop and default. 

Update your code to develop branch. As I said before you should never code in either of these two branches. Split up your work into many number of features. Then start a feature branch. For starting feature branch click on HgFlow in source tree. Now you will see an option to start a new feature as in figure below.

Click on`Start a New Feature`.On clicking they will ask you for the feature name.The prefix feature/ will be added to your feature's name.

Now you can see the feature branch you started in your branches section in source tree as in figure below.The feature branch will be generated from the develop branch.

Now you can start working on this feature as you do now. Once the feature is completed and you feel like giving the build to the internal testers, finish your feature branch by clicking on the HgFlow.Just check the popup that appears to see finish feature option. Once you finish the feature, the feature branch will get disappeared in the branches section of source tree. The feature branch will automatically merged to the develop branch.Now, in the same way as you started a feature branch, start a release branch. The release branch will be started from the develop branch and therefore now will have all code from your first feature.The internal testing build should be given from this branch. All issues raised by the internal testers on that completed feature should be fixed in this branch.

Once the build is stable you can finish your release branch in the same way as you finished your feature branch. Finishing your release means that the code now you have in that branch is a stable one. Finishing your release branch will merge the code in that branch to both default branch and develop branch.

We can run a release and a new feature at the same time. Only thing is you will have to resolve any merge conflicts that arise when you finish your second feature.The main point or the main advantage is that the default branch will be always having the stable code which means the client will get build from this default branch.

Once the client starts raising some bugs based on the build given to them, you will have to start a new hotfix branch the same way as above.It will be originated from the default bramch. Fix the issue as early as possible and finish the hotfix. Finishing it will merge the code to both default and develop.

The flow will continue like this.

But if you are using client app like tortoise-Hg then you will have to everything manually using terminal commands. Here, for initialising repository with hg flow download the hg-flow.py from hgflow.py and place it some where in your system. Then edit your .hgrc file in the repository and add the following content.

[extensions]
hgflow = /PATH/TO/hgflow.py

Then change directory in terminal to your repository folder and initialize your repository using terminal command

hg flow init

When  asked for branch names, use default names

Branch name for production release : [default] 
Branch name for "next release" development : [develop] 

How to name your supporting branch prefixes?
Feature branches? [feature/] 
Release branches? [release/] 
Hotfix branches? [hotfix/] 
Version tag prefix? [] 

This following command will create a new feature branch . Hg will switch this branch automatically.

hg flow feature start <name>

Finish a feature

hg flow feature finish <name>

This command will close the feature branch. The content in this branch will merge to the develop branch.

Switch between feature branch

hg flow feature switch <name>

This command will switch the branch between feature branches.

Close feature

hg flow feature close <name>

Close this branch and drop the code.
Similarly for release branch and hotfix. For more commands , refer HgFlowManual

Conclusion

The diagram below says it all.

 From this flow a new developer coming into the project can easily understand at what point he can get a stable build(default branch) , at what point a particular feature was implemented etc. Code review can be done on the development branch. Continuous integration servers can distinguish builds based on the branch from which build got triggered and can deploy it to corresponding environments.

In short, just follow HgFlow , this will certainly make your life easier.