Archive:Development/Tutorials/Git/KdeOnGit

Currently, Amarok and Konversation are testing out git to help with KDE's migration. There are also one or two kde-related projects that have started on gitorious (although this is *not* recommended yet!)

TODO:

• Explain where to find various kde projects and modules.
• Explain how to clone them.
• readonly-use guide
• contributing:
  • quick guide to gitorious website (copy content from amarok) (this should probably be spread between this page and the Pushing one.)

How KDE projects on Gitorious.org are set up

First up, a brief description of the Gitorious.org user and permission model:

• Individual user accounts can be organized into teams. Teams have members and administrators. Administrators can add new members and administrators, as well as edit a team's description.

• A project can be owned by either a team or an individual user account. A project can have one or more repositories.

• The repositories of a project have an owner as well, which can be distinct from the owner of the project. Again the owner can be a team or an individual user account.

• Any individual repository has a list of collaborators. A collaborator can be either a team or an individual user account and can have any combination of these three flags: commit (allows pushing commits), admin (allows editing the repository's description and settings, including the collaborator list) and review (allows processing merge requests).

KDE currently operates the kde-developers and kde-sysadmin teams on Gitorious.org, as well as several <appname>-reviewers teams (e.g. konversation-reviewers). The purpose of each of these can best be illustrated by examining how a KDE project on Gitorious.org has to be set up:

• The project is owned by kde-developers.
• The project's repositories are owned by kde-developers.
• The repositories belonging to the project have the 'kde-developers' team as a collaborator with the and only the 'commit' flag.
• The repositories also have 'kde-sysadmin' as a collaborator, with the and only the 'admin' flag.
• And they have an '<appname>-reviewers' team as a collaborator with the and only the 'review' flag.
• They also optionally have one or more key developers of the project as collaborators with the and only the 'admin' flag.

Commit access is thus handled exclusively via kde-developers, and any member of kde-developers can commit to any KDE repository. Getting into kde-developers is done by filing a KDE sysadmin request against the gitorious component, which is then implemented by one of the administrators of the kde-developers team.

The kde-sysadmin team exists for the purpose of making sure KDE's sysadmin squad can edit all KDE repositories on Gitorious.org, to fix issues or help people in a bind.

The '<appname>-reviewers' teams were originally created to be able to remove the 'review' flag from kde-developers for all the repositories, because otherwise every kde-developers member got email notifications about every merge request for every project. So someone with no interest in Amarok or Konversation would still get MR mail about them. Project-specific reviewers teams solve that routing problem. The reviewers teams usually have all the core developers from a project as members, and are administrated by one or more key developers.

Now, about those optionally-added key developers with the 'admin' flag: Pushing a tag into a repository requires being allowed to do a "force push". Force pushing can be enabled/disabled on a per-repository basis on Gitorious.org by anyone who has the 'admin' flag for a repository. As outlined above, this currently means every member of the kde-sysadmin team - as well as one or more key developers from a given project that have been added individually with the 'admin' flag. Thus the the main motivation for this is to allow projects to push tags without having to involve KDE's sysadmin team.

Enable post-update hooks

The post-update hooks enable features like the CCMAIL:, BUG: filters and emails the kde-commits mailing list.

The remote hooks repo has the scripts that set all this up. However just send the old SVN url and the new git:// url to Ian Monroe (eean in #kde-git) and he will set it up on the Amarok server.

Projects already on Gitorious

• Amarok - KDE's favorite music player.
• Konversation - an IRC client for KDE.
• kde-qt - KDE’s copy of Qt, containing the latest release, plus patches for Qt that haven’t been accepted (yet) by Qt Software.

FIXME: Is this a KDE project? Why are permissions not set for kde-developers?

• Project Silk - We've been working with gitorious as an experiment.
• Gluon - Gluon project, a game library which started on gitorious.

http://gitorious.org/+kde-developers has a more up-to-date list of kde-run projects. However, that list includes projects that don't use kde frameworks (like KDE developers' personal projects), and experiments, and isn't sorted in any way. We plan to have a better directory of kde-related projects once git.kde.org is up.

Setting up your KDE project to start developing in Gitorious

Ok, consider that things are ready to move your own project to Gitorious and you wanna know what you have to do. Let's start doing it together.

First of all, you should subscribe to Gitorious and move there your project. This will not be explained here... :)

Now you need to ask KDE sysadmins from here to include your account in the +kde-developers group. Give a couple of days to sysadmins to value your request and (hopefully) accept it. Now you have one project in Gitorious (and you own it) created with an account included in kde-developers group.

Next step is moving ownership of your project to the group. In this way, every kde developer will be enabled to collaborate to your project. :) To do this, mail Gitorious support team asking to move yourproject ownership to the kde-developers group. Given that, you have to ask again KDE sysadmin to properly set up your project. Just read about that, didn't you?

Now your repository is quite ready. You need still to do just something:

• ask Albert Astals Cid to point the scripty bot to your git repo (He'll ask you your main branch name and your repo push url)
• ask Ian Monroe to add the post commit hooks to your repo, to let things as the keyword BUG: and CCBUG: work
• ask (again) the KDE sysadmins to get integration into lxr.kde.org working
• ask Allen Winter to get integration into EBN working

(note: can I include their kde mail here?)

That's all! In a couple of days your git repo will be ready.

Happy hacking with KDE!