Development/Tutorials/Git/Feature Development Workflow/Simple Branch Development
This tutorial can help casual developers as well as developers with a limited knowledge of git to get started quickly. It covers the entire work flow, from developing in branches to getting them merged and integrated for the next release.
This tutorial does not require any git-specific knowledge.
Before you start, you are strongly advised to read the following documents:
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
The approach described in this document helps us implement proper quality evaluation for code that ends up in the main repositories while still allowing developers to work on anything they want. It provides a sane merging strategy which does not require any special git knowledge from the contributing developer's side.
To learn more about the rationale behind this approach, please read the Rationale article.
Setting up the development environment
The following steps assume your system is set up as shown in the git.kde.org user manual, especially regarding 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
The Recipe
git clone kde:kdelibs
git remote add integration kde:clones/kdelibs/dafre/kdelibs-integration
git fetch integration
The Explanation
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
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 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 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 Merge strategies to and from integration