Development/Tutorials/Git/Feature Development Workflow

    From KDE TechBase
    Revision as of 14:50, 27 April 2011 by Drf (talk | contribs)
    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.


    Some KDE Components have adopted an integration-staging-origin policy for pushing features into KDE's repositories. This document is designed to get developers started with this workflow and understand the steps involved.

    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.

    This is achieved by using two separate repositories. One is origin, the official project repository, where just maintainers are allowed to push, apart from special cases. The other is integration, where work in progress happens, and everyone can create branches and work on that.

    There are two separate figures: developers and maintainers. Developers are people who want to work on features on a specific repositories, maintainers are the gatekeepers for those repositories. Please note the purpose of the maintainer is purely organizational: no special power over technical decision is given to maintainers.

    A developer would provide his code into a remote branch in integration: as soon as this code is ready and reviewed, the maintainer would take care of merging into integration/master first, prepare for staging in integration/staging, and finally merge into master when needed.

    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!

    Note
    Advanced users might want to use integration as their origin


    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-explainatory 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
    

    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