[Kde-scm-interest] Layout of Git repositories for KDE

[Thiago Macieira]

I've been thinking of how the KDE server would lay out its repositories 
when (:->) we switch to Git, and here's what I've been thinking:

other/
  kde-common.git
  www.git
  kdewiki.git
  promo.git
  quality.git
  tests.git

stable.git/
  kdesupport.git/
    qimageblitz.git
    qca.git
    strigi.git
    [...]
  KDE.git/
    kdelibs.git
    kdepimlibs.git
    kdebase.git
    kdeaccessibility.git
    kdevelop.git
    kdeedu.git
    [...]
  extragear.git/
    libs.git/
      [...]
    multimedia.git/
      amarok.git
      [...]
    graphics.git/
      kphotoalbum.git
      [...]
    network.git/
      konversation.git
      [...]
    base.git/
      [...]
    [...]
  playground.git/
    libs.git/
      [...]
    base.git/
      [...]
    multimedia.git/
      [...]
    [...]
  kdereview.git/
    app1.git
    app2.git
    [...]
  l10n.git/
    af.git
    ar.git
    be.git
    [...]
  koffice.git
  qt-copy.git

releases/
  KDE.git/
    kdelibs.git
    kdepimlibs.git
    kdebase.git
    kdeaccessibility.git
    kdevelop.git
    kdeedu.git
    [...]
    kde-l10n.git
  app1.git
  app2.git
  amarok.git
  qca.git
  qimageblitz.git
  koffice.git
  konversation.git
  strigi.git
  [...]

projects/
  [...]
users/
  [...]
blackhole/
  [...]

Legend:
- ending in ".git" indicates a repository
- ending in ".git/" indicates a "supermodule" repository -- i.e., 
   a repository with submodule links. The directory with the same base 
   name also exists and contains the submodule repositories
- ending in "/" indicates a simple directory

Notes on the layout above:
1) The "other" part is something I haven't thought through yet. I don't 
know how those repositories are laid out today and how people using them 
work. 
  In special, the "www" repository is very ACL-limited to guarantee that 
the public pages are modified only by trusted people. Do we want to keep 
that policy? If so, how do we implement it?

2) The "stable" tree is the official tree. That's where any new 
contributor would start looking for the code contributing to KDE. That's 
also where most people would branch from and merge from, as well as their 
final merge objective.
  Equivalent to Subversion "trunk" and "branch/module". (I.e., trunk 
becomes the master branch, the version branches are also branches)

3) the "releases" tree is where releases are kept with proper tags of all 
released versions of each software.
  Equivalent to Subversion "tags"

4) the "projects" tree is where named projects are undertaken. The layout 
is not specified. 
  Named projects are those that have a declared objective. Therefore, they 
also have a life time: when the goal is reached, the code is merged back 
into "stable" and the repository is deleted. If the project is abandoned, 
the code is also merged, but with merge strategy "ours".
  For organisation purposes, each project repository is tied to a 
mandatory wiki page that describes the project, who's working on it, etc.
  Equivalent to Subversion "branches/work"

5) the "users" tree is where any user can create his/her own private 
repositories. The first level of this tree is the user name. Under each 
user directory, any number of repositories or sub-directories can exist, 
in any layout.
  No Subversion equivalent.

6) the "blackhole" tree is where dead code is moved to, one repository per 
unit of code being dropped. Probably with two top-level directories, 3 
and 4, for organisation purposes.
  In general, when a full module repository is deprecated, it is simply 
moved from "stable" with a server-side mv command. If the deprecation is 
only a subdirectory of a module, I don't really have a recommendation -- 
it depends on how the "copy-with-history" feature progresses.

7) note the absence of an l10n release repository, but a kde-l10n.git 
repository appearing. Each of the released modules must take care of its 
own l10n merging. I don't know how yet.

8) there will have to be an easy way of creating repositories in "users" 
and in "projects", without going through sysadmins. One feature of this 
interface is to also specify a source repository for the cloning (this 
will also set up alternates correctly). A repository can be created from 
the scratch (for new or unrelated tasks) too.
  By the same token, deleting said repositories must also be made easy.

9) note on alternates: repositories in "stable" and "releases" have no 
alternates. That is, they have full copy of the objects. At most, stable 
and releases can share hard links.
  Repositories in "users" and "projects" have an alternate set up when 
cloning. But the alternate should be only pointing to either stable or 
releases, never anything else. Therefore, if the repository being cloned 
isn't one of those, the cloning should be made in two steps:
  - clone the final stable or releases target, with alternates
  - clone the intended repository, with object copy (possibly hardlinking)
  The reason for this is that repositories in "users" and "projects" can 
be deleted, so there must be no alternate reference to them.

10) deleting a repository in "stable" (i.e., moving to blackhole) also 
involves an exhaustive search in all repositories on the server to find 
out if any alternate is set up pointing to it. If there is any, then the 
repository cannot be deleted.
  The rationale is that a code is blackholed when it is unmaintained and 
deprecated. If an alternate is set up, then someone is still using it or 
working on it.

11) repositories in "releases" are never deleted nor renamed. This begs 
the question: what happens if a logical module is renamed or dropped from 
a release (think kdeaddons, for instance: it is part of KDE 3, but has 
been removed in KDE 4 in favour of the extragear tree)?

12) should repository creation in "stable" and "releases" be done through 
sysadmins?

13) the layout I propose works for the following push access policy:
 - releases: only official maintainers and trusted lieutenants 
   (fall-backs) have push access. Sysadmins are involved when a change in 
   maintainership happens.
 - projects: push access only to the group of people working in said 
   project.
 - users: push access only to the user in question.
 - stable: push access to everyone. [controversial]

14) work is encouraged to happen in "projects" and "users" whenever 
possible

15) the kde-commits mailing list monitors commits to all repositories 
except those in "users". For filtering and organisation purposes, each 
commit refers to the "canonical" source in the "stable" tree, which is 
where the project was originally cloned from anyways.

-- 
  Thiago Macieira  -  thiago (AT) macieira.info - thiago (AT) kde.org
    PGP/GPG: 0x6EF45358; fingerprint:
    E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
Url : http://mail.kde.org/pipermail/kde-scm-interest/attachments/20071101/0e2453f8/attachment.pgp