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.

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

git fetch--all

Now, fetch from integration to retrieve the changes:

git fetch integration

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

git rebase integration/master

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.

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

git checkout integration-master

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

git reset--hard integration/master

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:

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.

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:

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.

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

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.

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.

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.

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.