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 tutorial on Github. For more information about Github see our page about Hacking:Tools.

Branch model

First you should know little bit about our workflow. Right now we work with the Gitflow model of named branches.

• master - 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.
• release-x.x.x - used for feature freeze state before the next major release. And for preparing the next minor release.
• feature-issue# - branch that contains a code for unfinished features. Contains code for new or improved features. Merge to develop. (e.g. feature-155 to name your fix for issue #155)
• hotfix-x.x.x - Create from develop and master. Contains a quick fix. Merge to master (or release) and develop.

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 develop/release branch. This mean all your changes in your local repository will be only in develop/release branch.
• Don't forget each day sync your repository with ours and merge new code in develop/release branch -> to your develop/release branch. Fix all merge conflicts.
• You can push your develop/release 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 push your develop/release branch to the upstream repository.
• If we ask you to fix some issues related to your changes continue commit them to the develop/release 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.

NOTE: INSERT UPDATED, GIT BASED, WORKFLOW EXAMPLE HERE

• As open source community we try to be open as possible. This mean if your changes fix something, extend or add new feature and not goes against our goals we will merge such a patch. Even if this patch is not perfect. This rule guarantee that you will not stuck with requests to fix your changes. We will help you by continue working with your code after merging.
• It is easiest for others to understand your intent if you follow naming conventions. Please use a convention of creating a branch to save your work in the github repository. For example, a fix for an issue from the list would go in a branch named issue-xxx. See the github handbook for more information about how to use the github tools.
• Please start your changes from the Seamly2D repository develop branch. For this run command hg update name_of_branch. Which branch to select depend on in which state the code base is now. See section Branch model. If you are not sure, please, ask for help.
• Before starting committing your changes open your????. For this run command hg branch -f develop.
• Now you are ready to begin work. Make some changes and commit them with command hg commit -m "Commit comment.".
• When you are ready open new 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.
• If your changes related to issue you can control an issue status by creating a commit with special description like this "ref #XXX. <Text of an issue description>". Where XXX is a number of an 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.
• Don't need to close a named branch.
• If you want to make several pull requests per time return to head develop/release branch and open another feature branch head. 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.