| Warning |
|---|
| This page contains rough working notes from discussion sessions at Platform 11, the contents of which may not accurately reflect any decisions made. Please do not infer anything from these notes, official summaries of the conclusions reached will be made available for discussion as soon as possible. |
This document outlines a recommended workflow for software maintained in KDE git repositories. It's not mandatory; it still has to be tested and adapted according to the experience we gain with it. But it reflects the results of a series of discussions of members of various groups within and outside of KDE taking into account experience from other projects and the proven workflows of KDE with SVN.
The intention is to have a workflow, which is a natural evolution of the SVN based workflow, providing a simple procedure for simple projects, but being able to scale to complex projects with more sophisticated requirements. The workflow is supposed to keep a constant flow of development, while still accommodating to the needs of being able to release stable code to users.
The master branch is the central branch of completed features and improvements. It is the origin for development branches as well as release branches. Code in master is supposed to be done, tested, and ready for being branched for a release. In theory a distribution should be able to take a snapshot of master, go through their QA procedures, and then give stable packages to end users.
All non-trivial commits should be first done in feature branches, being tested and reviewed, and only then merged to master, when they are done and stable.
Master is never frozen for new features or string changes. These freezes happen in release branches.
Development of features and bug fixes, which require a significant amount of code changes, happens in feature branches. These branches are branched off master. Developers are free to handle these branches according to their own needs, but when they are merged into master they need to be done, tested and reviewed.
When feature branches are merged into master, they need to be done, tested, and reviewed. The level of review depends on the policies of the module, and the significance of the change. Libraries will have stricter policies than leaf modules, central applications with a larger developer base will have stricter policies than smaller applications maintained by single persons.
Ideally broad testing of feature branches happens before being merged to master, including testing by developers who haven't worked on the changes. To facilitate this testing the use of integration branches is recommended, which collect changes from feature branches and make them available to a wider audience.
To make the development happening in individual feature branches available to a wider audience, the use of integration branches is recommended. Integration branches are maintained by individuals or groups of maintainers. They collect changes from feature branches, which are ready for review by fellow developers and which are done to a state where they are considered to be ready by the developer.
Integration branches are supposed to be usable for people who want to use or look at the latest state of development and are willing to report or fix bugs. Integration branches should not contain changes known to be broken. These branches are made visible and accessible to a developer audience beyond the people working on the actual features.
Integration branches are not merged into master. Rather, the branches that were merged into these integration branches are merged directly into master after going through any integration and testing.
Release branches are branched off master for doing releases. The branch is made when the release goes into feature and string freeze. No feature development and no string changes are done in release branches. They are there for final stabilization and QA of a release and generating release tarballs. The release branch is tagged with the version number, when creating a release tarball.
Fixes going into the release branches are done in the release branch and then merged to master, so master keeps getting all fixes made in release branches, which apply to master.
When developing in a local branch, changes should always be rebased before pushing them to the remote origin. This keeps a simple linear history. Rebasing can be thought of as applying changes as patches to the latest version of the code. In case of conflicts they need to be adapted. So developers always patch against the latest version of the code.
Remote branches are shared by multiple people. Rebasing them causes different people to have different versions of history, which causes conflicts, inconsistent and hard to understand states. So remote branches should never be rebased. Merging them properly also reflects that development actually happened in a side line.
The workflow is driven by social contract. All contributors have the same technical access rights. There are no formal roles. Those who do the work decide according to the shared values and principles of the community.
To support the social nature of development, it is also recommended that all personal branches are pushed as soon as possible so that others may participate as well. Even if the developer is unsure if the branch will be merged or achieve their goals, branches should be pushed to the central repository during their development.
This is a collection of procedures for typical use cases. Details might be different according to the policies of different sub communities, but they should always adhere to the general principles of the KDE Git Workflow. This is not an exhausting or authoritative list, but an illustration of how to apply the basic principles in practice.
Ideally we would have examples with commented git commands how exactly to go through the procedures.
When done:
If approved:
(Note the lack of an integration branch in this case. In the case of smaller projects, the overhead of an integration branch may not be offset by the benefits.)
If rejected:
If remote feature branch doesn't exist yet:
If remote feature branch already exists:
When done:
If approved:
If rejected:
If remote feature branch does not exist yet:
If remote feature branch already exists:
When done:
When testing successful:
patches
If approved:
If rejected because of a minor issue:
If rejected because of a major issue:
KDE Community Wiki 