< Development | Tutorials | Git/Feature Development WorkflowRevision as of 18:08, 27 April 2011 by Drf (talk | contribs)(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff) link title 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 casual developers or developers with limited git knowledge started for developing their own branches, and get them merged and integrated. This tutorial does not require any git-specific knowledge. Before you start, you are strongly advised to read the following documents: Which repository should I use? Contents 1 Repositories and projects complying with this policy 2 Rationale 3 Setting up the development environment 3.1 Cloning the repository and adding integration 3.2 Creating branches 3.3 Using integration vs. using your own clone 4 Developing a new feature 4.1 Creating a new branch 4.2 Synchronizing the branch with master 4.3 Getting the branch reviewed 4.3.1 Rebase your branch onto integration/master 4.3.2 Push your changes to integration 4.3.3 Submit the branch for review 4.4 Getting the branch approved 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 the Rationale article. Setting up the development environment In the following steps, we will 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 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 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. This involves three easy steps: Rebase your branch onto integration/master It is important to have your branch rebased to be ready for review. Rebasing puts your commits on top of anything else of the branch you are rebasing on, including the changes from that branch. You of course want to rebase onto integration/master. To do that, issue git rebase integration/master Be sure to fetch before doing that. At this stage, conflicts might occur: be sure to fix them and commit/push the result. You will be required to force push at this stage. Warning Rebasing must be done at this stage only: please avoid rebasing before getting reviewed or after getting reviewed if not strictly necessary 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 one, please have your mentor push your branch for you. Submit the branch for review Use Reviewboard for getting your branch reviewed. You can read KDE Reviewboard+Git tutorial for getting started. Getting the branch approved After your branch has been reviewed and marked as "Ship it!" at least by one of the maintainers of the code you are adding features to, your branch is ready for integration and staging. Your reviewer will inform one of the repository's maintainers of that. Your work is done at this stage: the maintainer will integrate and stage your branch for you, and will merge it into origin according to the project's merging policy. You will be CCMailed upon every separate step your branch will take on its way to origin/master Retrieved from "https://techbase.kde.org/index.php?title=Development/Tutorials/Git/Feature_Development_Workflow/Simple_Branch_Development&oldid=58509" Content is available under Creative Commons License SA 4.0 unless otherwise noted.