git workflow draft

[Aaron J. Seigo]

hi all....

so after the meeting on Sunday, here is where we are in terms of a draft 
workflow. more complete meeting minutes can be seen here:

	http://titanpad.com/SnJwFW2iXL

the goal of the meeting was to come up with a draft of a mutually agreeable 
git workflow for kdelibs and kde-runtime. the hope is that this can become a 
template for the rest of the SC modules (kde-workspace will follow the kdelibs 
workflow, for instance), as well as as many other KDE projects as possible. 
this is to help ensure a general continuity to how we work across KDE.

Topic Branches
=============

All new development should happen in a branch. Git makes branches very cheap 
and they can be local or remote. There are few if any really good reasons not 
to use branches, so development directly in master should be generally 
discouraged.

Topic / feature branches should be public and pushed to the main repository 
where they are easy for others to find and collaborate on. They should start 
as a branch off of master. We do not want git to become, even unintentionally, 
a road to segregated, private development at the expense of our collaboration 
as a community. With public branches in a shared repository, even a git pull 
will inform of new development that is happening. Git then becomes an 
important piece of our development communication with each other: a new branch 
means new activity.

Only features / topics that are intended from the state to be merged with 
master should end up in the main repository, however. More experimental and/or 
long term efforts (an example presented was the kconfig refactor leading up to 
4.0) should start in a personal clone, and when/if the work crosses the border 
into "this is realistically going to be merged with master" it can be moved 
into a branch in the main repository.

After merge with master, topic branches should be deleted from the main 
repository.

Branch Naming: if a branch is specific to a subproject, e.g. solid, specify it 
in the branch name such as "solid/udevbackend". This will make it easier to 
use git branch listings (along with grep, etc) to pick out branches of 
interest based on the project in question. If there is not a sepcific 
subproject that it belongs to, give it a good descriptive name such as 
"pluggable-kconfig". 

No branches should be prefixed with "KDE"; we consider that a reserved name. 
Nor topic should branches be numeric in nature (such as a version number) as 
those are reserved for actual release branches. (Sys admin at the meeting 
indicated that it is likely they will eventually put a push hook in place that 
prevents such "incorrectly" named branches.)

Branch names should not include the committer name as we have git log and it 
will help discourage "ego coding" where one person has overt "ownership" of 
the branch. This is still a team effort after all :)

"Dead" branches: on every maor every release, a check will be done on branches 
in the main repository. Any branches that have not seen any work done on them 
in the last <TBD: 12? 18?> months  will be deleted. Deleted branches are 
backed up automatically on git.kde.org, so work will be retrievable. This will 
keep our branch count sane over the years.

Open questions / topics for further discovery:

	* documenting best practices for keeping a topic branch in sync with 
master, keeping in mind that later a merge from the topic branch to master 
needs to be done and the git history sould be kept as clean as possible

	* process for announcing that a branch is ready to be merged so as to 
gather feedback (particularly important for the shared "crown jewels" in 
kdelibs); this is something like a "kdereview 2.0" though on the level of 
feature branches.

	* topic branches and our release cycle: is it acceptable to create a new 
topic branch even when we are in feature freeze?

	* more advanced workflows involving, e.g., an integration branch is not 
something we seem equipped for right now as it brings overhead and additional 
coordination with it. Perhaps in the future though ....

	* best practice "recipes" for merging, e.g. using "git merge --log"

Bugfixes
=======
The big question here was forward-porting vs. backporting. Backporting has the 
advantage that it is what we do currently and people run and test master more. 
Forward-porting ensures that all bug fixes in the stable release branch end up 
in the master branch and it is easier to test against a branch with fewer 
changes (e.g. new features). It will take discipline either way: two bug fixes 
we found in 4.6 that weren't in master.

Merge is prefered over cherry-pick: it cleans up the git history a bit; each 
commit is only there once instead of the cloned commits created by cherry-
pick.

The two methods (forward vs backward ports) are not mutually exclusive: on the 
contrary, backporting commits that made it into master can make it easier for 
the next person who wants to merge the stable branch into master.

Generally, we will encourage people to develop and test bug fixes against the 
stable branch and forward port them by way of a merge into master. Due to the 
obvious cases for exceptions, this will not be a "hard and fast" rule.

Documenting best practices considerations
==================================

There is a lot we need to document. The above needs to be refined, fleshed out 
and turned into point-by-point documentation. There are many pages on Techbase 
that need updating as a result of moving from svn to git as well. I'll 
organize and hopefully also host a docu day on irc for this specifically once 
the dust settles a bit more.


We'll need to have further discussion on these topics and your feedback is 
welcome. Questions as well as answers are valuable, as both will help define 
what needs to be further defined and documented.

-- 
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Qt Development Frameworks
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20110215/f1166ae2/attachment.sig>