Development/Tutorials/Git/Feature Development Workflow/Rationale and Explanation of Workflow
This page is meant to provide an overview of the workflow used in KDE and the lifecycle of a feature/bugfix branch. It is great to get you started and running in minutes, but does not provide an in-depth look of all the knowledge involved. Please refer to other separate articles for better insights.
The problem
KDE is a huge project where lots of different people commit new code. This process used to be held back by several entry level barriers, including but not limited to release cycle freezes and backporting policies. The transition to git set the base for an improved system which would lower contribution barriers, but a new contribution system should be created to fully take advantage of the new infrastructure.
The solution
The workflow we decided to adopt is the branch-integration-staging workflow, which is shown in the picture below.
This workflow implies that any non-trivial task is done into a separate branch by the user, and that the origin repository should not be a development ground, but rather a place where code gets merged when ready for general consumption. All development work happens in the integration repository.
The split repository approach
As shown in the picture, this approach uses two separate repositories. You should seldom care about both: the general rule is that if you are a developer, you should use integration, whereas if you are a packager or a tester, you should stick with origin.
Please read Which repository should I use? to learn more on this topic.
Branch creation and handling
When developing a new feature, you should always work on a branch originated from integration/master. During the development, you can merge integration/master into your branch anytime, but you are NOT allowed to merge other branches into it. Please contact a repository maintainer if you need to do that.
When your branch is ready for review, you should submit it to ReviewBoard. Once reviewed, depending on your developer status and level of expertise, you should let a maintainer take care of merging into integration/master for you, or merge the branch yourself. Usually, you do not want to merge yourself unless you are perfectly aware of KDE's merging workflow and strategy.
Integration is kept up-to-date with what's happening with master by maintainers. Please avoid merging anything back into integration: it is a delicate process which should be done by maintainers only, in order to keep the merging history linear. You are just supposed to merge integration/master into your feature branch if needed.
Please read Stuff to learn more on this topic.
Integration and staging explained
Integration and staging are two parts of the merging process which happen in the integration repository. When a branch has been reviewed and is accepted for merge, is rebased onto integration/master and merged into it. integration/master is what developers should use: at this point, the branch is available for consumption to the whole development base.
Depending on the branch itself, the branch might get staged immediately or not. integration/staging is the place where this happens: staging is a phase where branches are prepared for being merged back into origin. Every monday (unless some freeze policies are active), integration/staging is merged back into origin/master by maintainers, making the feature available for consumption for everyone, and including it in the next release.
Usually, simple branches are staged immediately. Branches which depend on other branches are usually put on hold to be staged together, whereas big branches or branches which affect critical code, and might then cause regressions, have a 2-weeks grace period in integration/master, and get staged afterwards if no troubles arise.
Please read the staging phase explained to learn more on this topic.
The Maintainers' role
Repository maintainers are members of the KDE community who handle merges between branches and repository. Their main role is to make sure all the policies are always applied, and origin/master always remains safe and committed to the policies and workflow of the KDE project.
In particular, maintainers:
- Have a deep knowledge of git and of KDE's workflow
- Take care of merging branches (after they have been reviewed) into integration if the developer has no rights for doing that
- Take care of staging branches after they have been merged into master according to the staging policy
- Take care of supervising the staging->origin/master operation
- Are the people to refer to whenever in doubt about git policies
Each repository has at least two maintainers.
For detailed information about maintainers, please refer to the Maintainers wiki page.