Hacking:Making pull requests: Difference between revisions

Content added Content deleted

Inline

Latest revision as of 00:34, 13 October 2018

The intended audience for this page is anyone who wants to contribute to the open source project and is not a member of the core development team. To be added to the core development team requires special privileges and access that can be granted by the repository owner. If you wish to become a member of the core team, please make a request on the forum.

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[edit | edit source]

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, 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.

General recommendations[edit | edit source]

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, or adds a new feature and and does conflict with the project our goals we will merge such a patch. Even if this patch is not perfect. 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. See the github handbook for more information about how to use the github tools.
Please start your changes from the Seamly2D repository develop branch. You may use the fork command to create your own copy of the repository. If you are not sure, please, ask for help in the forum.

Working with feature development[edit | edit source]

Implement a feature step by step and save your progress.
Please make commit back to the develop branch only if you have finished a step. There is no reason to make a commit for a partially finished step today. You can continue tomorrow. The interim code may be stored in your cloned copy of the repository or in a feature branch.
Each commit should be small as possible and contain one logical step of developing a feature. This will help us better understand your code. The member of the core development team who does the review and merge for the commit may be in a different geographic area and time zone. The project is primarily staffed by volunteers. For these reasons, we will sometimes see changes associated with each commit separately.
Before a commit is made, the code should be successfully compiled.
Make all your commits in your local develop branch. This mean all your changes in your local repository will be only in develop branch.
Don't forget each day sync your repository with ours and merge new code from the fashionfreedom develop branch -> to your develop branch. Fix all merge conflicts.
You can push your develop branch to github. This will help us watch your progress and leave comments. We recommend that you 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 github. It will automatically update your pull request.

@@ Line 1: / Line 1: @@
 __TOC__
+The intended audience for this page is anyone who wants to contribute to the open source project and is not a member of the core development team.  To be added to the core development team requires special privileges and access that can be granted by the repository owner.  If you wish to become a member of the core team, please make a request on the [https://forum.seamly.net/c/developer forum].
 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#Mercurial|Hacking:Tools]].
+'''Note:''' this is not a tutorial on Github. For more information about Github see our page about [[Hacking:Tools#Mercurial|Hacking:Tools]].
 == Branch model ==
-First you should know little bit about our workflow. Right now we work with several [https://www.mercurial-scm.org/wiki/NamedBranches named branches].
+First you should know little bit about our workflow. Right now we work with [https://github.com/FashionFreedom/Seamly2D/blob/develop/CONTRIBUTING.md the Gitflow model of named branches].
-* ''default'' - used only for releases.
+* ''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'' - branch that contains a code for unfinished features.
+* ''feature-issue#'' - branch that contains a code for unfinished, new, or improved features. Merge to develop. (e.g. feature-155 to name your fix for issue #155)
-* ''release'' - used for feature freeze state before the next major release. And for preparing the next minor release.
+* ''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 feature branch. This mean all your changes in your local repository will be only in feature branch. When you will decide that all were done create a pull request. Merge your feature branch with our develop.
-* Don't forget each day sync your repository and ours and merge new code in develop -> to your feature branch. Fix all possible 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.
 == General recommendations ==
 There are several things you should know for successful creating a pull request.
+ NOTE: INSERT UPDATED, GIT BASED, WORKFLOW EXAMPLE HERE
-[[File:Workflow mercurial.png|center]]
+* As open source community we try to be open as possible. This mean if your changes fix something, or adds a new feature and and does conflict with the project our goals we will merge such a patch. Even if this patch is not perfect. We will help you by continue working with your code after merging.
-* Please, read carefully official tutorial from Atlassian [https://www.atlassian.com/git/tutorials/making-a-pull-request 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.'''
+* 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.  See [https://guides.github.com/introduction/git-handbook/ the github handbook] for more information about how to use the github tools.
-* Normally you are not allowed create new named branches. You should use '''develop''', '''feature''' or '''release''' depend on a purpose.
+* Please start your changes from  [https://github.com/FashionFreedom/Seamly2D/tree/develop the Seamly2D repository '''develop''' branch]. You may use the fork command to create your own copy of the repository.  If you are not sure, please, ask for help in the [https://forum.seamly.net/c/developer forum].
-* 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, [http://stevelosh.com/blog/2009/08/a-guide-to-branching-in-mercurial/ A Guide to Branching in Mercurial]). See [[Hacking:Tools#Mercurial|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 [https://confluence.atlassian.com/bitbucket/resolve-issues-automatically-when-users-push-code-221451126.html 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.
+== Working with feature development ==
-''Little bonus. You can find all successfully merged pull requests [https://bitbucket.org/dismine/valentina/pull-requests/?state=MERGED here]. These are good example if you want to find how look correctly made pull requests.''
+* Implement a feature step by step and save your progress.
+* Please make commit back to the develop branch only if you have finished a step. There is no reason to make a commit for a partially finished step today. You can continue tomorrow.  The interim code may be stored in your cloned copy of the repository or in a feature branch.
+* Each commit should be small as possible and contain one logical step of developing a feature. This will help us better understand your code. The member of the core development team who does the review and merge for the commit may be in a different geographic area and time zone. The project is primarily staffed by volunteers. For these reasons, we will sometimes see changes associated with each commit separately.
+* Before a commit is made, the code should be successfully compiled.
+* Make all your commits in your local '''develop''' branch. This mean all your changes in your local repository will be only in '''develop''' branch.
+* Don't forget each day sync your repository with ours and merge new code from the fashionfreedom '''develop''' branch -> to your '''develop''' branch. Fix all merge conflicts.
+* You can push your '''develop''' branch to github. This will help us watch your progress and leave comments. We recommend that you 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 github. It will automatically update your pull request.