FlightGear Git: splitting FGData

Aircraft are split to seperate Git repositories, under the FlightGear Aircraft project at Gitorious.

Reasons to split fgdata

• Advantages
  • Aircraft authors can get commit access to their own aircraft, without granting them global fgdata access.
  • When pulling fgdata, one won't have to download several gigs of aircraft data. People will have to pull the base package, but any additional aircraft will be optional.
  • It will be easier for aircraft authors to check the history of their aircraft.
  • Commiting will go faster, because Git will no longer have to check those thousands of files to see whether they were edited.
  • fgdata size decreased from 9,34 GB to 1,78 GB.
• Disadvantages
  • It will be harder to keep a local up to date copy of all aircraft. No more "git pull" to fetch all the latest updates.
    • Might be fixed by using Git submodules.
  • How to deal with licences? Until now there was a COPYING file in fgdata. When aircraft are split in seperate repositories, they'll likely need to include a license reference themselves.
  • Need a concept for release management, maintaining version numbers, release branches, release tags et. al.

Reasons to put aircraft under a single project

• Advantages
  • The current fgdata-developers team can access any single aircraft, for easy/quick fixes. For example when something is found to be wrong and copied among several aircraft (which happens due to copy&paste). Or when something about the sim itself changes and aircraft msut be adapted to run on an upcoming release.
  • When an aircraft developers decides to leave, the repo can easily be taken over by other developers. If the author set up his own repository, we'd have to create a new repository (and thus change all references/links).
  • It allows us to use the bug tracker for aircraft. Most developers won't clone aircraft repos from all kind of places, just to help fixing bugs.
• Disadvantages
  • Authors won't be able to choose their own license.
    • The FlightGear Aircraft project has been set to "License: Other/Multiple". This allows (in theory, we first need to agree on this) any aircraft author to add whatever license file to his/her aircraft and still put it under the project.

Starting new aircraft

New aircraft should not be commited to fgdata. A separate repository should be created instead. Contact a FlightGear Aircraft admin to get your repository included in the FlightGear Aircraft project. You, as author, will get commit rights for that repository.

The current fgdata developers will have access to every single aircraft repository. In order to maintain aircraft that no longer have an active author, fix global bugs etc. Other users can create merge requests to get their fixes/improvements commited.

Step 1: Split aircraft into separate repositories

Aircraft are split into "private" repositories, under the FlightGear Aircraft project. Repositories for all aircraft in current fgdata have been created as of 17 October. Repository names equal directory-names (with the exceptions of dots (.) and capitals (ABC), as those are not supported by Gitorious.

There are two workflows that both do the trick:

Method 1

Note: the split branch (737-300-split in this example) must NOT exist beforehand.

cd $FG_ROOT 
git subtree split -P Aircraft/737-300 -b 737-300-split
mkdir -p ../split-aircraft/737-300
cd ../split-aircraft/737-300
git init
git fetch $FG_ROOT 737-300-split
git checkout -b master FETCH_HEAD
git push git@gitorious.org:flightgear-aircraft/737-300.git master

Method 2

(need to check this one)

cd fgdata
git clone --no-hardlinks /fgdata /737-300
git filter-branch --subdirectory-filter Aircraft/737-300 HEAD -- --all
git reset --hard
rm -rf .git/refs/original/
git reflog expire --expire=now --all
git gc --aggressive --prune=now

Then all aircraft should be pushed to their new repositories. A script will take care of that.

Step 2: Remove all aircraft from fgdata

Fgdata is frozen, all commit privileges revoked. Meanwhile, a new fgdata repository without any aircraft is created, pushed to gitorious and finally tested.

Step 3: Write/update manuals

Since the aircraft development flow will be different, we should teach our developers how to use the new system.

To be written:

• FlightGear Git: aircraft authors

To be updated:

• FlightGear and Git
• FlightGear Git on Mac OS X
• FlightGear Git on Windows

Step 4: Switch fgdata

Once tests show that the new repository is working fine and no data has been lost, the repositories will be switched. The exisiting repository is renamed, and the new repository takes its place and access to the new repository is setup. The historic fgdata is kept but stays frozen, at least until we're sure everything is safe. It may also be a good idea to keep the existing repo, since it contains release branches - which are not part of the new repository and would be lost otherwise.

Step 5: Inform the crowd

Post an announcement at the mailing list, forum, Facebook (?) and in the upcoming newsletter edition. Link to the respective wiki articles (see Step 3) that contain details on how to work with the new system.

Questions

• What to do with Aircraft/UIUC should it be placed like "one" aircraft in a aircraft-repository? Or each individual?
  • An flightgear-aircraft/UIUC repo has been created, we can delete it if needed later on.
• Gitorious does not support dots in repository names.
  • For now we just skipped dots, so Supermarine-S.6B has a repo called supermarine-s6b (note that Gitorious also does not distinct capitals. This does not seem to be a problem though, since git clone uses the original directory name).
• What rights should aircraft authors get?
  • Commit/review might be best. If they are granted admin rights, they can delete the repo and remove the fgdata-developers as collaborators. When they do the later, there's no way we can regain control over the repo. We won't even be able to delete it from the FlightGear Aircraft project.

References