Development/Tutorials/Git/Feature Development Workflow/Branch Development With Merge - Revision history

AnneW: moved Archive:Development/Tutorials/Git/Feature Development Workflow/Branch Development With Merge to Development/Tutorials/Git/Feature Development Workflow/Branch Development With Merge: revert

2012-03-24T19:43:38Z

moved Archive:Development/Tutorials/Git/Feature Development Workflow/Branch Development With Merge to Development/Tutorials/Git/Feature Development Workflow/Branch Development With Merge: revert

AnneW: moved Development/Tutorials/Git/Feature Development Workflow/Branch Development With Merge to Archive:Development/Tutorials/Git/Feature Development Workflow/Branch Development With Merge

2012-03-24T19:17:25Z

moved Development/Tutorials/Git/Feature Development Workflow/Branch Development With Merge to Archive:Development/Tutorials/Git/Feature Development Workflow/Branch Development With Merge

Neverendingo: Text replace - "`" to ""`


2011-06-29T21:08:17Z
Text replace - "<code lang="bash">" to "<syntaxhighlight lang="bash">"

				
				
				
				
			
			← Older revision
			Revision as of 21:08, 29 June 2011
			
Line 15:
Line 15:
  ====Rebase the branch onto master====   ====Rebase the branch onto master====
  =====The Recipe=====   =====The Recipe=====
− <code lang="bash">git checkout add-hello-button + <syntaxhighlight lang="bash">git checkout add-hello-button
  git fetch --all   git fetch --all
  git rebase integration/master</syntaxhighlight>   git rebase integration/master</syntaxhighlight>
Line 23:
Line 23:
  Checkout your branch by issuing   Checkout your branch by issuing
    
− <code lang="bash">git checkout add-hello-button</syntaxhighlight> + <syntaxhighlight lang="bash">git checkout add-hello-button</syntaxhighlight>
    
  Before performing the actual rebase, make sure all your remotes are synced with latest changes. To do that, issue   Before performing the actual rebase, make sure all your remotes are synced with latest changes. To do that, issue
    
− <code lang="bash">git fetch --all</syntaxhighlight> + <syntaxhighlight lang="bash">git fetch --all</syntaxhighlight>
    
  Now, fetch from integration to retrieve the changes:   Now, fetch from integration to retrieve the changes:
    
− <code lang="bash">git fetch integration</syntaxhighlight> + <syntaxhighlight lang="bash">git fetch integration</syntaxhighlight>
    
  At this point, you can rebase your branch onto master. Issue   At this point, you can rebase your branch onto master. Issue
    
− <code lang="bash">git rebase integration/master</syntaxhighlight> + <syntaxhighlight lang="bash">git rebase integration/master</syntaxhighlight>
    
  When rebasing, all the commits of your branch are put on top of the commits of the branch you are rebasing. This allows to keep a clean and linear history.   When rebasing, all the commits of your branch are put on top of the commits of the branch you are rebasing. This allows to keep a clean and linear history.
Line 43:
Line 43:
  ====Merge the branch into master====   ====Merge the branch into master====
  =====The Recipe=====   =====The Recipe=====
− <code lang="bash">git checkout integration-master + <syntaxhighlight lang="bash">git checkout integration-master
  git reset --hard integration/master   git reset --hard integration/master
  git merge --no-ff add-hello-button</syntaxhighlight>   git merge --no-ff add-hello-button</syntaxhighlight>
Line 50:
Line 50:
  First of all, get back to your local branch tracking ''integration/master'' by issuing   First of all, get back to your local branch tracking ''integration/master'' by issuing
    
− <code lang="bash">git checkout integration-master</syntaxhighlight> + <syntaxhighlight lang="bash">git checkout integration-master</syntaxhighlight>
    
  You now need to make sure that your local branch matches 1:1 the remote ''integration/master'' branch. For this reason, you have to reset the local branch to the remote one.   You now need to make sure that your local branch matches 1:1 the remote ''integration/master'' branch. For this reason, you have to reset the local branch to the remote one.
Line 58:
Line 58:
  This is done when issuing   This is done when issuing
    
− <code lang="bash">git reset --hard integration/master</syntaxhighlight> + <syntaxhighlight lang="bash">git reset --hard integration/master</syntaxhighlight>
    
  It is now time to perform the actual merge. Due to our rebase, the merge will be fast-forward (if you are here, you should know what it means, and why this happens). However, our policy implies to have a merge commit containing relevant information belonging to the branch we are merging. For this, we have to tell git to perform a ''non-fast-forward'' merge. This is done through this command:   It is now time to perform the actual merge. Due to our rebase, the merge will be fast-forward (if you are here, you should know what it means, and why this happens). However, our policy implies to have a merge commit containing relevant information belonging to the branch we are merging. For this, we have to tell git to perform a ''non-fast-forward'' merge. This is done through this command:
    
− <code lang="bash">git merge --no-ff add-hello-button</syntaxhighlight> + <syntaxhighlight lang="bash">git merge --no-ff add-hello-button</syntaxhighlight>

`Neverendingo: Text replace - "`" to ""

2011-06-29T20:51:42Z

Text replace - "</code>" to "</syntaxhighlight>"

Drf at 18:46, 27 April 2011

2011-04-27T18:46:37Z

Drf: Created page with '{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }} This tutorial is aimed...'

2011-04-27T18:40:59Z

Created page with '{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }} This tutorial is aimed...'

New page

{{warning|This page refers to a draft policy which is still to be agreed and implemented. Please take it as a reference for a work in progress project. }}

This tutorial is aimed to get core developers with more-than-average git knowledge started for developing their own branches, and get them merged and integrated.

This tutorial require you to have a good understanding of git, especially regarding rebasing, merging and committing.

Before you start, you are strongly advised to read the following documents:

* [[Development/Tutorials/Git/Feature_Development_Workflow/Repository_Roles|Which repository should I use?]]
* [[Development/Tutorials/Git/Feature_Development_Workflow/Rebase_vs_Merge|Rebasing vs. merging: why and how]]

===Merging your branch into integration/master===
Merging your branch is a critical part, and it is a delicate process you should undertake only if you are confident with what you are doing and knowing what it implies. The merging process is done with the following several steps.

====Rebase the branch onto master====
=====The Recipe=====
<code lang="bash">git checkout add-hello-button
git fetch --all
git rebase integration/master</code>

=====The Explanation=====

Checkout your branch by issuing

<code lang="bash">git checkout add-hello-button</code>

Before performing the actual rebase, make sure all your remotes are synced with latest changes. To do that, issue

<code lang="bash">git fetch --all</code>

Now, fetch from integration to retrieve the changes:

<code lang="bash">git fetch integration</code>

At this point, you can rebase your branch onto master. Issue

<code lang="bash">git rebase integration/master</code>

When rebasing, all the commits of your branch are put on top of the commits of the branch you are rebasing. This allows to keep a clean and linear history.

Of course, at this stage conflicts might occur. Be sure to have your branch cleanly rebased before proceeding. A good practice is to verify if the history is now linear as expected. You can use ''git log'' or any git UI for doing that.

====Merge the branch into master====
=====The Recipe=====
<code lang="bash">git checkout integration-master
git reset --hard integration/master
git merge --no-ff add-hello-button</code>

=====The Explanation=====
First of all, get back to your local branch tracking ''integration/master'' by issuing

<code lang="bash">git checkout integration-master</code>

{{note|When working with multiple remotes, you can issue ''git fetch --all'' to update all the remotes tracked by your local copy }}

===Repositories and projects complying with this policy===
The following repositories/projects follow these guidelines. Any project not mentioned here is unaffected by what described

* kde-workspace
* kde-runtime
* kdelibs (plasma only)

===Rationale===
This approach is meant to implement proper quality evaluation into the main repositories, still allowing developers to work on anything they want, and providing a sane merging strategy which does not require any specific knowledge from the developer's side.

To learn more about the rationale behind this approach, please read [[Development/Tutorials/Git/Feature_Development_Workflow/Rationale|the Rationale article]].

===Setting up the development environment===
In the following steps, we will assume your system is set up as shown in the [http://community.kde.org/Sysadmin/GitKdeOrgManual git.kde.org user manual], especially regarding [http://community.kde.org/Sysadmin/GitKdeOrgManual#Let_Git_rewrite_URL_prefixes automatic URL rewriting for KDE repositories] enabled.

In the following tutorial, we'll refer to kdelibs as the main target, but this applies to any other repository using this policy.

====Cloning the repository and adding integration====
To clone the repository, issue

git clone kde:kdelibs

This will create a kdelibs directory containing the whole repository. You now need to add a separate remote for handling ''integration''. A remote is a repository URL, and your local clone can contain multiple repositories to track different branches. To add kdelibs' ''integration'' repository, issue inside kdelibs' clone:

git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration

Now, fetch from integration to retrieve the changes:

git fetch integration

{{note|When working with multiple remotes, you can issue ''git fetch --all'' to update all the remotes tracked by your local copy }}

====Creating branches====
You now need to get your branches set up, in particular ''integration/master''. In this example, we are creating a new branch named ''integration-master'' which would serve for this purpose in particular:

git checkout -b integration-master integration/master

This command creates a local branch set to track a remote one. This branch should be the branch you'll be basing your work upon: origin/master is not meant for development!

====Using integration vs. using your own clone====
It is ''strongly'' advised to push your work to integration, but under some circumstances (your work is extremely big in size, you do not have a KDE Development account, etc.), it is allowed to push your branches to a separate personal clone. All work should end up into integration for being reviewed anyway.

===Developing a new feature===
We'll now walk through the process needed to develop a new feature. We'll suppose you want to add a button which says "hello" to a specific part of code.

====Creating a new branch====
First thing to do is creating a new branch on which to base your work on. This branch must be based upon ''integration/master''. To make sure this happens, start by issuing

git checkout integration-master

Now create your branch. Give it a self-exeplainatory name: try to keep branches as atomic as possible, and possibly split big changes throughout multiple branches divided as per topic. In our case, we want to name our branch ''add-hello-button''. To do that, we do:

git checkout -b add-hello-button

That will create our personal branch which is going to contain our work. Push your branch to integration by issuing

git push integration add-hello-button

====Synchronizing the branch with master====
When you create a branch (like you did), you are not receiving incremental updates from other people working in the repository (so in the ''master'' branch). This is usually not an issue, and instead an advantage: you can work on your code without being affected by other changes.

However, there are some cases in which ''synchronizing'' your code with what's been going on with master is required. Git gives you two ways for doing that: merging or rebasing. Both have upsides and downsides, and both come at a cost.

For this reason, you are ''strongly'' invited to avoid merging or rebasing on top of master while developing your feature whenever possible. Although, if you need to, you are supposed to merge your branch with master, and not to rebase it. What you need to do is the following:

git fetch --all
git merge integration/master

This command merges your work with the very latest code from ''integration/master''. This process comes with a cost: your branch will not be a candidate for a clean rebase, and each merge makes the history more complex.

Again, this means that you should try to avoid this process if possible, and if you ''absolutely'' need to do that, you should try and keep the number of merges you'll do in your branch as low as possible. More than 3 merges start to create a very cluttered history.

To learn more about merging, rebasing, and what this implies to your branch and to our merge strategy, you are invited to read [[Development/Tutorials/Git/Feature_Development_Workflow/Rebase_vs_Merge|Rebasing vs. merging: why and how]]

====Getting the branch reviewed====
Once you are done with your changes, you are ready to get your branch reviewed. In the review process, the project's core developers will evaluate your code's quality, and will help you in making it perfect before it gets integrated. Here's how to do it.

=====Push your changes to integration=====
If you have a KDE developer account, simply

git push integration add-hello-button

from within your ''add-hello-button'' branch.

If you do not have a KDE Developer account, please get in touch with the core developer who is mentoring you, or with one of the repository's maintainers to get your changes pushed into ''integration''.

=====Submit the branch for review=====
Use Reviewboard for getting your branch reviewed. You can read [[Development/Review_Board|KDE Reviewboard+Git tutorial]] for getting started and understanding the steps involved.

It is '''critical''' that you specify in the review request whether your branch has ever been merged with master or not.

=====Modifying the branch=====
Everytime you update your review request with new code, please remember to push changes to ''integration'' with your new code. That will help developers in reviewing and maintainers in handling your request.

====Getting your branch integrated====
Once your review request has been marked as "Ship it!", your job is done. The maintainers will take care of merging the branch into ''integration/master'', stage it for release, and make it reach ''origin'' in the end.

It is '''critical''' at this point to have your branch ''frozen''. You should not commit anything else to your branch and you should consider it dead. Maintainers will take over its commits and will delete it when merging occurs.

If you are curious to find out what happens to your commit after your code is accepted, read [[Development/Tutorials/Git/Feature_Development_Workflow/Merge_Strategies|Merge strategies to and from integration]]

← Older revision		Revision as of 18:46, 27 April 2011
Line 52:		Line 52:
	<code lang="bash">git checkout integration-master</code>		<code lang="bash">git checkout integration-master</code>

−	{{~~note~~\|~~When working with multiple remotes,~~ you ~~can issue~~ ''~~git fetch~~ -~~-all~~'' to ~~update all~~ the ~~remotes tracked by your local copy~~ }}	+	You now need to make sure that your local branch matches 1:1 the remote ''integration/master'' branch. For this reason, you have to reset the local branch to the remote one.
		+
		+	{{warning\|This process will erase '''any''' local change you made to your local ''integration-master'' branch which has not been pushed to ''integration/master''. This is the main reason why you should never do '''any''' work in integration-master, except for merging! }}
		+
		+	This is done when issuing
		+
		+	<code lang="bash">git reset --hard integration/master</code>
		+
		+	It is now time to perform the actual merge. Due to our rebase, the merge will be fast-forward (if you are here, you should know what it means, and why this happens). However, our policy implies to have a merge commit containing relevant information belonging to the branch we are merging. For this, we have to tell git to perform a ''non-fast-forward'' merge. This is done through this command:
		+
		+	<code lang="bash">git merge --no-ff add-hello-button</code>