Hacking:Making pull requests

This page describes how to create a pull request. We highly recommend you to read this page before you will decide to send us your changes.

Note: this is not a mercurial tutorial. For more information about mercurial see our page about Hacking:Tools.

Branch model

First you should know little bit about our workflow. Right now we work with several named branches.

• default - used only for releases.
• develop - branch that contains a code for the next major release. Code in this branch good enough for testing and sharing among developers.
• feature - branch that contains a code for unfinished features.
• release - used for feature freeze state before the next major release. And for preparing the next minor release.

These are the main branches you should know about. There are several long term task specific branches in repository too. But we will not discuss them in this document.

Working with feature

• Make a feature step by step and save your progress.
• Make commit only if you have finished a step. Don't need to make commit for unfinished step today. You can continue tomorrow.
• Each commit should be small as possible and contain one logical step of developing a feature. This will help us better understand your code. Sometimes we see changes per each commit separately.
• Compiler should successfully build each commit you made.
• Make all your commits in feature branch. This mean all your changes in your local repository will be only in feature branch.
• Don't forget each day sync your repository with ours and merge new code in develop branch -> to your feature branch. Fix all merge conflicts.
• You can push your feature branch to bitbucket. This will help us watch your progress and leave comments. We recommend don't hide your code until the end.
• When you will decide that all were done create a pull request. In settings set to merge your feature branch with our develop or release branch. See which branch is parent for your branch.
• If we ask you to fix some issues related to your changes continue commit them to the feature branch and push them to bitbucket. It will automatically update your pull request.

General recommendations

There are several things you should know for successful creating a pull request.

• Please, read carefully official tutorial from Atlassian Making a Pull Request. This tutorial will help you understand how to work with bitbucket web site. But don't forget to return to this page and read it all. We have warned you.
• Normally you are not allowed create new named branches. You should use develop, feature or release depend on a purpose.
• Be sure you use correct branch for your changes. This is the most popular mistake.
  • For very small/trivial patches (contains only one commit) use the develop named branch directly. If it's your first pull request better do it in feature branch.
  • For regular patches (contain several commits) you should use the branch feature (recommended way). Don't worry if repository already contains one. We can have as many as we need (so called anonymous heads, A Guide to Branching in Mercurial). See Mercurial useful commands to find out how to force opening new anonymous head for named branch.
• Add correct description for your pull request. It should contain string "Resolved (or Fixed) issue #XXX. <Text of an issue description>". Where XXX is a number of issue in the Issue Tracker. Read more about Resolving issues automatically when push code.
• Don't forget to add your changes to file ChangeLog.txt. But only if these changes brings new feature or fix a bug. For example fixing building of the source code is not enough reason to update a changelog.
• In the end push your changes to your fork, then create a pull request.
• In a pull request merge your develop/feature branch with our develop branch.
• Don't need to close a named branch.
• If you want to update pull request (for example we have asked you to fix some issues) just push your changes to the same branch that was used in a pull request. Bitbucket will automatically update a pull request.
• For fixing merge conflicts merge new code in develop branch -> to your feature branch.
• If you want to make several pull requests per time return to develop branch and "reopen" another feature branch. Repeat all previous steps.

Little bonus. You can find all successfully merged pull requests here. These are good example if you want to find how look correctly made pull requests.