FGAddon

From FlightGear wiki
Revision as of 15:39, 14 May 2016 by Bugman (talk | contribs) (Undo revision 98220 by Hooray (talk) - See http://wiki.flightgear.org/Talk:FGAddon#History_of_the_fgdata_split. This text is a duplication of the current text.)
Jump to navigation Jump to search

The official FGAddon aircraft hangar is a version control repository, hosted on FlightGear's SourceForge infrastructure, and used for the day-to-day development of FlightGear aircraft. FGAddon is an Apache Subversion version control repository. These are aircraft that are not part of the base package (the aircraft that are included in the base package — the Cessna 172P and the UFO — are still kept in the FGData repository), but are tagged with each stable release for the FlightGear download pages.

The FGAddon aircraft development repository should be considered unstable. When using a stable FlightGear release, it is best to obtain aircraft with a matching version number from the FlightGear download pages. However, as stable releases from FlightGear version 3.4 onwards are tagged and present within the FGAddon repository, the Subversion tools can be a convenient way to obtain individual aircraft or the entire official hangar of approximately 500 aircraft. Also, if using the lastest nightly releases or a self-compiled version of FlightGear from FlightGear's Git version control repositories, using FGAddon allows the aircraft to be updated to the latest development versions.

History

WIP.png Work in progress
This article or section will be worked on in the upcoming hours or days.
Note: The accuracy of the facts in this section are in the process of being verified.
See history for the latest developments.
Original Win95 icon

The FlightGear project was conceived on April 8, 1996 by David Murr who proposed a new flight simulator to be developed by volunteers[1][2][3][4]. Part of the initial goals were to develop 2D and 3D graphics routines for the simulator. However this was a huge task that came to an unfinished halt at the start of 1997 as the main developer, Eric Korpela, was finishing his thesis. Therefore starting on May 16, 1997, Curtis Olson relaunched development with a new project based on the OpenGL libraries, allowing a functional flight simulator to be put together in a short period of time[5]. The first commits were to the original flightgear and simgear CVS version control repositories.

As the project grew, so did the size, quantity, and quality of the FlightGear assets. These assets were not organised and were scattered across different parts of the internet. Therefore it was decided that much of this FlightGear content would be assembled and stored together in a new centralised CVS repository called fgdata, which was created on October 22, 2000. To allow for the legal redistribution of these assets as part of the FlightGear distribution, a GPLv2 only policy was adopted.

In May 2010, development was interrupted by the infamous "coffee incident" which resulted in the loss of Curtis' home server hosting all of the FlightGear repositories[6]. These events resulted in a mass migration of all the CVS repositories to Git repositories. Due to bandwidth issues, it was decided that the new repositories would be hosted on the Gitorious open source infrastructure.

With time as the project grew, the size and scope of the fgdata repository mushroomed so that a split was inevitable. A first splitting attempt was organised by Gijs de Rooy and announced on October 18, 2011[7]. Each aircraft was placed in its own Git repository and all aircraft linked back to fgdata using a Git submodule approach. However this attempt failed and was abandoned. From this date until the end of 2014, the design of the fgdata split was discussed on the development mailing list and summarised in the FlightGear Git: splitting fgdata wiki article. In the planning stages, the repositories were known as fgdata-old splitting into FGData (a.k.a. fgdata-new) and FGAddon (a.k.a. flightgear-aircraft and fgaircraft). After half a decade of planning, it was decided that the best solution for FlightGear aircraft development would be a single centralized Subversion repository. This would facilitate community management and maintenance of the aircraft while at the same time providing modularity and smaller downloads and smaller local repository sizes.

In late 2014, Gitorious, the provider of the open source infrastructure for the FlightGear source code and data repositories announced that it would shut its services down by May 2015 due to its acquisition by GitLab. This catalysed the split of fgdata-old and a switch to the SourceForge open source infrastructure for the hosting of the VC repositories. Other parts of the FlightGear infrastructure were already hosted by SourceForge, making the move a natural one. Sealing the deal, SourceForge agreed in writing to host the huge FlightGear aircraft collection, the size of which is unrivaled in open source circles. Today, the FGAddon SVN repository, together with most of the FlightGear project infrastructure, is hosted on SourceForge.

In August 2015, a new FlightGear policy document was written to codify the unwritten standards of the project[8]. With this document, the licensing policy for the FlightGear aircraft has been updated from being GPLv2-only to now being a GPLv2+ or GPL-compatible[9] stance. However, to combat licence proliferation complications for the integrity and good of the FlightGear project, it is strongly recommended that original content be GPLv2+ licensed.


Obtaining aircraft

Tip  If you are interested in obtaining aircraft for stable FlightGear releases and you are unaware of what version control is, you should visit the FlightGear hangars for downloading aircraft.
Caution  If the FlightGear and FGAddon aircraft versions do not match, strange bugs should be expected and the version-mismatch combination will not be supported by the FlightGear community.

With access to the Subversion (SVN) tools, the FGAddon version control repository can be a convenient way for obtaining aircraft for using within a specific FlightGear version directly from the official source. When using the nightly builds or a version controlled copy of FlightGear, the most up to date in-development versions of the aircraft should be used so the versions match. The following describes how to use the official repository to obtain aircraft from the perspective of a FlightGear user.

Preparation

To use the FGAddon repository, the Subversion tools need to be installed:

  • MS Windows: Install one of the many Subversion clients. For example SlikSVN is one of the best command line versions and the best for aircraft development, and TortoiseSVN provides a user friendly graphical user interface (GUI) by integrating into Windows Explorer.
  • Mac OS X: Install the official Subversion client.
  • GNU/Linux: Install the Subversion client via the package manager. This will usually be in a package called subversion-*.{rpm,deb}.

FGAddon directory layout

To know how to use the FGAddon repository, an understanding of the repository directory layout is essential.

  • /trunk: This base directory is where the in-development versions of the aircraft are located.
  • /branches/release-x.y.z/: These directories correspond to the specific stable FlightGear releases.

The web interface for the FGAddon repository allows all of the aircraft to be browsed.

Download

Aircraft to be downloaded

Firstly, choose an aircraft to download. The Bell Boeing V-22 Osprey will be used in this example.

Command line

To download the aircraft for FlightGear 3.4, simply type:

svn co https://svn.code.sf.net/p/flightgear/fgaddon/branches/release-3.4.0/Aircraft/V22-Osprey

To obtain the in-development version, type:

svn co https://svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/V22-Osprey

If all of the ~500 aircraft from the repository are desired - beware that this will be a huge download of over 6 GB - use the following command:

svn co https://svn.code.sf.net/p/flightgear/fgaddon/trunk flightgear-fgaddon

When using a stable FlightGear release, for example FlightGear 2016.1, to obtain all of the FGAddon aircraft to match the installed FlightGear version, use:

svn co https://svn.code.sf.net/p/flightgear/fgaddon/branches/release-2016.1 flightgear-fgaddon

GUI clients and TortoiseSVN

When using one of the Subversion GUIs (graphical user interfaces), simply copy one of the above https:// URLs and use that in the GUI (each GUI is different, so see the relevant documentation for help). For the unique TortoiseSVN tool, simply:

For more details, see the TortoiseSVN documentation. Note that there is an option to install the command line tools when installing TortoiseSVN.

Flying

To use the newly downloaded aircraft, please see the Howto:Install aircraft article, skipping the instructions for downloading and unzipping the aircraft.

Updates

With a checked out copy of the /trunk in-development version, the aircraft can be updated to the latest version using the command:

svn up

Aircraft development

Tip  The FlightGear community encourages aircraft development directly within FGAddon.

Contact the original aircraft authors

The first step for developing and advancing the aircraft of the official FlightGear hangar, or from one of the private hangars for that matter, is to make contact with the original aircraft author(s). Their names can be found within the *-set.xml file, within the <authors> XML tag. Often the contact email address will be listed in a README file or some other text file in the base aircraft directory. If not, contact can sometimes be established via the FlightGear development mailing list. Contacting the original authors is important to see if the aircraft is currently being actively developed, and if you can join in as part of the development team.

SourceForge account

To work on the official aircraft collection, a SourceForge account should first be set up. This will allow to either directly commit to the FGAddon repository, if commit access has been been granted, or to work in as part of a SourceForge development team. The registration process is lightning quick and the SourceForge developer infrastructure and developer services will be accessible in under a minute.

Commit access

Before obtaining commit access, an all-out effort to contact the original author(s) should be made to determine if the aircraft is actively being developed. If this is unsuccessful, sign up for the FlightGear development mailing list and ask for help there. If the aircraft has a current maintainer, you will be directed as to how to proceed with development. Otherwise ask if someone could volunteer to mentor you in the process of becoming an aircraft developer with full commit access.

To obtain commit access, you will first need:

  1. To demonstrate your capabilities and development skills.
  2. To show that you understand the FlightGear policy document.
  3. To show an understanding of the GPL licensing issues, and that you can be trusted not to use copyrighted, non-GPL material.
  4. To earn the trust of the FlightGear community.

These easy to jump over hurdles are simply designed to protect against repository corruption or pollution of the repository with illegal content.

To have your changes committed into the FGAddon repository, you should discuss and coordinate with the original aircraft author, or your mentor, for the best way to proceed. Depending on the development scenario, this maybe by merge request, file transfer, the primitive patch system, or any other convenient way. Once you believe you have proven your capabilities and you are knowledgeable about GPL licensing issues, you should write a mail to the development mailing list asking if you can be granted commit access, providing your SourceForge username.

FGAddon commitlog mailing list

To follow all changes which occur in the FGAddon repository, subscribe to the dedicated Flightgear FGAddon commitlogs mailing list. One email is sent per commit, as the commit is made.

Version control tools

To access FGAddon and use it for aircraft development, the Subversion or SVN version control tools are needed. Alternatively git-svn provides an interface for those who prefer the git version control tools.

Subversion

Set up

The FGAddon aircraft hangar is stored in a remote Subversion repository located on the SourceForge infrastructure, and therefore it is simplest to use the SVN tools for aircraft development and will cause the least problems. See the Subversion installation section for setting up the tool chain.

Repository checkout

The first step is to 'checkout' a copy of either the repository trunk or one of the aircraft in the trunk:

svn co <url> <dir>

For the relevant URL to use, you must chose one of the development scenarios and find the URL in that section. This command will create a local subversion repository copy in the given <dir> directory. Note that this will only contain the part of the FGAddon repository specified in the URL. This means that Subversion allows you to checkout either a single file all the way to the entire remote repository.

Information and history

At any point to see information about the local repository, type:

svn info

To see the history of the checked out copy of the repository, type one of:

svn log
svn log | less
svn log -v | less

Daily usage

The main Subversion command you will be using is:

svn add <path>

This will register the file or directory <path> within the local repository to allow it to later be 'committed' and sent to the remote repository. To move or rename a file or directory, use:

svn mv <path1> <path2>

This should be used rather than normal file moving/renaming so that the change is tracked in the local repository. To remove a file from the local repository, type:

svn rm <path>

To see the current status of the local repository, type:

svn st

Committing changes

All of the above operations only occur on the local repository copy - the remote FGAddon repository at SourceForge will know nothing of these changes. To send all your changes to FGAddon, you need to commit the changes:

svn ci

This will open up an editor to allow you to write an informative commit log message. When committing, it is best to make small modular commits so that each commit corresponds to a single purpose. Note that you can only commit to FGAddon if you have commit access.

Branching

The concept of Subversion branching is currently only used in the FlightGear project for tagging the stable releases. However if you are curious about branching, see the Branching and Merging chapter of the Subversion manual, and the svnmerge.py script which can greatly simplify the process.

Git-svn

The git-svn tool is useful for those who are already familiar with using git repositories, or those who wish to have their own private aircraft development playground. Git-svn provides a bridge between the remote FGAddon Subversion repository and a local git repository. For those unfamiliar with git, the git-svn bridge together with the git repository is far more complicated to use than the native Subversion tools. For more information on using git, see Howto:Start using git. The following will assume that only a single aircraft will be stored in the local git repository.

Set up

The git distributed version control system needs to first be installed.

Cloning a single aircraft

The first step is to 'clone' a copy of one of the aircraft in the remote Subversion trunk:

git svn clone <aircraft_url>

For the relevant aircraft URL to use, you must chose one of the development scenarios and find the URL in that section. The URL depends on your FGAddon commit access status. The clone command will create a local git repository containing solely the aircraft of interest, and initialise the git-svn bridge.

Information and history

At any point to see information about the local repository, type:

git svn info
git branch -vva
git remote -v

To see the history of the checked out copy of the repository, type:

git log

Daily usage

The main git command you will be using is:

git add <path>

This will register the file or directory <path> within the local repository to allow it to later be 'committed' to the local git repository. To move or rename a file or directory, use:

git mv <path1> <path2>

However note that git history is not as robust as svn history. See the git-svn file moving/renaming deficiency section for how to better perform this operation. To remove a file from the local repository, type:

git rm <path>

To see the current status of the local repository, type:

git status

Committing changes

As git is a distributed version control system, changes are committed to the local git repository.

git commit

This will open up an editor to allow you to write an informative commit log message. The commit is local and will not be sent to FGAddon.

Dedicated FGAddon branch

In the examples above, only a single branch was assumed in the repository. If interaction with a remote git repository or branching within the local git repository is desired, then a different strategy is required. The reason being that the branch that synchronises with FGAddon must preserve a linear history. This means only cherry-picking of the desired changes into that branch is allowed.

In this example, two branches will be set up in the local git repository:

  • fgaddon: This branch will be dedicated for FGAddon synchronisation and will preserve a linear history.
  • master: A master branch for aircraft development, allowing for mergers and other non-linear history operations.

Assuming a newly cloned repository, create the fgaddon branch with:

git branch fgaddon

And switch to that branch:

git checkout fgaddon

The FGAddon synchronisation can then be performed on this branch. To pull in the developments from the master branch, use cherry-picking to apply a sequentially ordered list of commit hashes:

git cherry-pick <commit hash 1>
git cherry-pick <commit hash 2>
git cherry-pick <commit hash 3>
...

To see the list of commits to be sent to FGAddon prior to dcommitting, type:

git log git-svn..HEAD

And to see the changes as a single diff:

git diff git-svn..HEAD

Synchronising

To send the changes to the remote FGAddon repository, firstly change to the dedicated fgaddon branch:

git checkout fgaddon

Make sure the local git-svn repository is up to date with all changes that have occurred in FGAddon:

git svn rebase

Then push or dcommit the changes to FGAddon with:

git svn dcommit

Deficiencies of git-svn

Warning  Performing a git-svn clone of the /trunk/ or entire repository is not recommended, as the entire repository history will be downloaded, resulting in a huge local repository, as well as putting a large strain on the FlightGear open source infrastructure.

There are a number of operations in which git-svn is deficient and the svn tools should be used instead.

Copying files between aircraft

Caution  Git-svn does not maintain the file copying history normally present in a Subversion repository.

The most important of these is the copying of content from other FGAddon aircraft. In this case you will need FGAddon commit access and a local svn copy of the repository. Firstly synchronise the repositories by dcommitting all changes back to FGAddon:

git svn dcommit

Then in the local svn repository, copy the file:

svn cp Aircraft/<aircraft1>/<file_path1> Aircraft/<aircraft2>/<file_path2>

And commit the change:

svn ci

Back in the local git-svn repository, pull in the new files:

git svn rebase

Using the subversion tools avoids the FGAddon repository backend from significantly increasing in size, as svn copies are cheap.

Moving or renaming files

Caution  Git-svn does not always maintain the file moving or renaming history normally present in a Subversion repository.

This problem stems from the fact that svn history is more robust than that of git. The svn mv and git mv commands are not equivalent. The subversion command stores the move history directly in the repository whereas git does not (git instead uses heuristic methods to try to detect history, after the commit). The result of using git-svn is that often the move will not be detected and the FGAddon history will show one file or directory being deleted and another added. This also causes the repository backend to increase in size, whereas svn mv will not cause any significant size increase. If you wish to have a better historical record in the FGAddon repository and be considerate to the repository backend, it is recommended that you temporarily switch to the subversion tools. Firstly, synchronise the repositories:

git svn dcommit

Then in the local svn repository, move or rename the file:

svn mv Aircraft/<aircraft>/<file_path1> Aircraft/<aircraft>/<file_path2>

And commit the change:

svn ci

Back in the local git-svn repository, pull in the changes with:

git svn rebase

Copying files within one aircraft

Just as the svn mv command stores the move information directly within the repository, so does svn cp store the copy information. Therefore if you would like to duplicate a text file and modify it, using the native Subversion tools instead of git-svn for this operation allows for the file history to be permanently preserved in the FGAddon repository.

Subversion properties

Caution  Git-svn currently only supports the svn:executable property, all other properties are ignored and cannot be added, changed, or removed in a git-svn clone of the aircraft.

Internally, Subversion identifies binary files using the svn:mime-type repository property. However as git-svn cannot set this property when using the git add command, the result is that binary files will be treated as text. Binary diffs will be seen when using svn diff or git diff, and a binary diff will be shown in the FGAddon commitlog mailing list messages. As this issue is not unique to git-svn, to work around this issue please see the binary diffs section.

FGAddon development concepts

New aircraft

To add a new aircraft to the FGAddon repository, the SVN tools are required. If you encounter svn:mime-type property problems when adding a new aircraft, see the mime-type problems section for how to resolve the issue. Or if you have a svn:executable property problem, see the executable flag problem section.

svn import

Warning  The svn import command described herein will send all contents of the specified directory directly into FGAddon without warning and without a way to cancel the operation. Therefore special care must be taken when specifying the directory to upload into FGAddon, as well as the target FGAddon directory. See the svn add section below for a safer way to add a new aircraft.

The svn import command is the easiest method to use and does not require a local copy of the repository to be checked out. To start:

  1. Create an empty local aircraft directory.
  2. Copy the aircraft files into this directory.
  3. Carefully check all files to make sure there are no hidden or temporary files that should not be uploaded to FGAddon.

Assuming the Dead Simple Human Powered Airplane (DaSH PA or "DaSH") aircraft as an example, located in the DaSH/ directory, on the command line run:

svn import DaSH/ svn+ssh://<username>@svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/ -m \
    "Initial import of the DaSH human powered aircraft.\n\nFor details see the forum thread at http://forum.flightgear.org/viewtopic.php?f=4&t=24495 ."

Where <username> is the SourceForge user name. This will add all the files into FGAddon with commit log message with the summary line Initial import of the DaSH human powered aircraft., followed by a blank line, and then a detailed description pointing to the original location or discussion of the aircraft. To see if the aircraft has been successfully added to the repository:

svn list svn+ssh://<username>@svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/DaSH/

Or visit the FGAddon web interface. The aircraft can then be checked out as described in the Development scenarios section.

svn add

If a local copy of the FGAddon trunk is present, then the svn add command can be used instead. This is far safer than the svn import command, as the change can be double checked before committing. In the Aircraft/ directory of the local repository, create the DaSH/ directory. This can either be empty or contain all files of the initial aircraft. Then on the command line, add the aircraft to the local repository:

svn add DaSH/

Then double check the changes prior to committing:

svn st

And send the changes to FGAddon with:

svn ci

An editor, often vi[10], will open and the commit message can be composed. Alternatively the commit log message can be specified on the command line with:

svn ci -m "<subject_line>\n\n<detailed_description>"

Commit blocking by pre-commit hooks

Sometimes when committing to FGAddon, the commit will be blocked the following will be printed out:

svn: E165001: Commit failed (details follow):
svn: E165001: Commit blocked by pre-commit hook (exit code 1) with output:

This is due to the presence of two repository pre-commit hook scripts which check the quality of the commit, blocking it if a text file is set to a binary file mime-type or if the executable flag is set. These scripts are simply to protect the repository and to keep it clean.

Mime-type problems

Sometimes when attempting to commit files to FGAddon using the SVN tools, the commit will be blocked with the following message:

Sending        dash-set.xml
svn: E165001: Commit failed (details follow):
svn: E165001: Commit blocked by pre-commit hook (exit code 1) with output:

Aborting the commit, the svn:mime-type property is labelling the following text
files as binary:

  dash-set.xml:  svn:mime-type=application/xml

Before committing, please remove this property by typing 'svn propdel svn:mime-
type file_name' for all affected files.  This will allow the text files to be
treated as text within the FGAddon repository.

To avoid the svn:mime-type property being incorrectly set by your subversion
client, the subversion configuration file at $HOME/.subversion/config or
%appdata%\roaming\subversion\config should be edited and a new entry added to
[auto-props] for each affected file type.  In most cases, the problem is with
XML files being labelled as "application/xml" by a library called libmagic.  To
override this, add the following to the svn config file:

*.xml = svn:mime-type=text/xml

svn: E165001: Your commit message was left in a temporary file:
svn: E165001:    '/flightgear/repo_testing/svn-commit.tmp'

Despite messages about adding or sending files, no change will have occurred in the FGAddon repository. This message is created by a repository pre-commit hook script which checks if the Subversion svn:mime-type property is set on a list of known text files and, if the mime-type is set to a binary format, the commit is blocked. The reason for this block is to protect the repository. Newer SVN clients rely on a 3rd party library known as libmagic which will detect the aircraft XML files as the binary mime-type of application/xml. The result is that the XML files are treated as binary files in the repository. This behaviour is completely undesirable, as changes cannot be followed on the flightgear-fgaddon-commitlogs mailing list or in the repository history, and the size of the commits become orders of magnitude larger. Therefore this buggy behaviour has been blocked for the protection of the FlightGear project. To remove the problem, follow the instructions in the message and, using the command line tools, type:

svn propdel svn:mime-type <file_name>

Repeat this for each text file listed in the error message. Then commit again, using the commit message saved in the svn-commit.tmp file. The message file name will be reported in the commit failure message, but check its contents first:

cat svn-commit.tmp

And reperform the commit:

svn ci -F svn-commit.tmp
Subversion config file

The automatic property setting of svn:mime-type can be controlled by modifying the Subversion config file. Firstly in the [miscellany] section, make sure that the auto-properties are turned on:

enable-auto-props = yes

Then in the [auto-props] section, add:

*.ac = svn:mime-type=text/plain
*.eff = svn:mime-type=text/xml
*.frag = svn:mime-type=text/plain
*.nas = svn:mime-type=text/plain
*.osgx = svn:mime-type=text/xml
*.svg = svn:mime-type=text/svg+xml
*.txt = svn:mime-type=text/plain
*.vert = svn:mime-type=text/plain
*.xhtml = svn:mime-type=text/xml
*.xml = svn:mime-type=text/xml
*.xsl = svn:mime-type=text/xml

These are all the text files that the hook script will check that the mime-type is set to a text format, though new text files will likely be added in the future. These additions can either be to the user configuration file located at ~/.subversion/config (or %USERPROFILE%\AppData\Roaming\Subversion\config in Windows) or, if a user configuration file is not set, to the global configuration file at /etc/subversion/config (or %APPDATA%\Subversion\config in Windows).

Executable flag

Another blocking message when attempting to commit files to FGAddon using the SVN tools is:

Adding         dash-set.xml
Transmitting file data .svn: E165001: Commit failed (details follow):
svn: E165001: Commit blocked by pre-commit hook (exit code 1) with output:

The svn:executable property is set on the files ['dash-set.xml'], aborting the
commit.

The current policy is that no executable files are allowed in FGAddon.  Before
committing, please remove this property by typing 'svn propdel svn:executable
file_name' for all affected files.  Or to remove it recursively from all files
to be committed, in your aircraft directory type 'svn propdel svn:executable
-R'.

To avoid the svn:executable property being set by your subversion client, on
GNU/Linux and Mac OS X systems simply make sure that the file's execute bit is
not set before adding the file to be committed.

svn: E165001: Your commit message was left in a temporary file:
svn: E165001:    '/flightgear/repo_testing/svn-commit.tmp'

This will probably only be seen on Mac OS X and GNU/Linux systems. This message is printed by a pre-commit repository hook script that checks if the Subversion svn:executable property is set and, if so, the commit is blocked. This is a security measure, as no aircraft files should be executable. To remove the problem, follow the instructions in the message and, using the command line tools, type:

svn propdel svn:executable -R

Then commit again, using the commit message saved in the svn-commit.tmp file. The message file name will be reported in the commit failure message, but check its contents first:

cat svn-commit.tmp

And the reperform the commit:

svn ci -F svn-commit.tmp

Binary diffs

Warning  The incorrect setting or absence of the mime-type property on a binary file will result in a binary diff.

When looking at the output of svn diff (or git diff if you are using git-svn) as well as when reading messages from the FGAddon commitlog mailing list, you may see a large number of unrecognisable characters. This is the result of what is known as a binary diff, showing the binary file differences as if it were text. Although this is not a issue for the operation of the repository, the situation is an aesthetic problem which makes it more difficult to perform a review of the changes.

To fix the problem, firstly the binary files with the svn:mime-type property missing need to be identified. The following subversion command can be used:

svn propget svn:mime-type <file_name>

As it can be tedious checking each file individually, the following Python script simplifies and automates the process to identify all binary files with a mime-type issue:

Fixing the problem

As git-svn cannot set or change the svn:mime-type property, a svn checkout copy of the aircraft is required. The property can then be set to the default Subversion binary mime-type with:

svn propset svn:mime-type "application/octet-stream" <file_name>

Alternatively, the following set of shell commands can be used to automate the process:

SourceForge developer services

The FlightGear project is hosted on the SourceForge open source infrastructure. This developer services section will highlight some of the useful tools you can take advantage of. SourceForge consists of two categories of services:

Project infrastructure
The FlightGear project uses the project services of SourceForge. These services are for standalone software projects.
Developer infrastructure
These are services available to anyone with a SourceForge account, and are available via your SourceForge homepage and accessible to all. This includes being able to create multiple version control repositories (svn, git, hg), wikis, forums, development teams, blogs, and ticket trackers (for bugs, support requests, tasks, etc.).

Rather than creating a new project, any development for the FlightGear project should be based on the developer infrastructure.

Developer git repository

To set up your own remote git repository, here for developing the FGAddon fkdr1 aircraft:

  • On your profile page at https://sourceforge.net/u/<username>/profile/, go to Admin -> Add New -> Git.
  • Set label to fkdr1 FGAddon git-svn repository.
  • Set the code path to code-fkdr1. The code-* prefix is to differentiate this from the forum-*, wiki-*, and other directories.

The repository will be located at https://sourceforge.net/u/<username>/code-fkdr1/ci/master/tree/.

Development teams

If you and a group of friends would like to privately develop one of the FGAddon aircraft as a team, assuming that the you have contacted the original aircraft authors and the aircraft is not actively being developed, then you should create a SourceForge development team. A team leader should be appointed to set this up under their SourceForge account. Assuming you wish to develop the "ornithopter" aircraft, the steps are:

  • Go to Personal tools -> Admin.
  • Click on User Permissions.
  • Click on Add a new group at the bottom.
  • Set the name to ornithopter, and save.
  • Click on Add in the ornithopter group and add the SourceForge names of all your team members.

After setting up a private repository in the team leader's account, as described below, then the development team should be set up for the repository.

  • Go to the repository under your SourceForge account.
  • Click on Admin - <repository name>, then select Permissions.
  • In the Write section, remove Developer and add ornithopter.
  • Click on Save.

The development team will then have commit access to the private repository.

Team communications

To help with team development, the SourceForge infrastructure allows for multiple dedicated discussion forums to be created. This can either be within a SourceForge project or under a SourceForge users homepage. This allows the team leader to create a forum dedicated solely to the development of the aircraft of interest. Continuing with the ornithopter example, the steps for the team leader are simple:

  • On your profile page at https://sourceforge.net/u/<username>/profile/, go to Personal tools -> Admin.
  • Click on the Tools option in the left hand menu.
  • Click on Discussion in the Click to install section.
  • Change the label to Ornithopter forum, and the path to forum-ornithopter, for example. The forum-* prefix is to differentiate this from the code-*, wiki-*, and other directories.
  • Click on Save.

More details are given on the SourceForge Discussion documentation.

Development scenarios

Individual developer

Note  Development scenario: You are an individual developer and will use the native Subversion tools.

This is by far the simplest development scenario and should be used in most cases. If you are using the command line Subversion client, you can checkout an individual aircraft with:

svn co svn+ssh://&lt;username&gt;@svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/wrightFlyer1903

Where <username> is your SourceForge user name. Alternatively you can checkout all aircraft with:

svn co svn+ssh://&lt;username&gt;@svn.code.sf.net/p/flightgear/fgaddon/trunk flightgear-fgaddon

If you do not have commit access, type one of:

svn co https://svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/wrightFlyer1903
svn co https://svn.code.sf.net/p/flightgear/fgaddon/trunk flightgear-fgaddon

To use the new local svn repository, see the subversion instructions.

Individual developer (git-svn)

Note  Development scenario: You are an individual developer and will use the git-svn tools.

This is more complicated than using the native SVN tools, but can be useful without having FGAddon commit access, as multiple local commits can be made to be sent to the original aircraft authors or to the development mailing list/forum. To clone the aircraft of choice into a new git repository, type:

git svn clone svn+ssh://<username>@svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/<aircraft>

Where <username> is your infrastructure user name and <aircraft> is the directory name in the FGAddon repository. If you do not have commit access, instead type:

git svn clone https://svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/<aircraft>

To use the new local git repository, see the git-svn instructions and its deficiencies.

Upload to Sourceforge

To share the local developments, the changes can be uploaded to a remote git repository on the SourceForge infrastructure. For this, a developer git repository should first be set up under your SourceForge profile. Then add this as a remote:

git remote add origin ssh://<username>@git.code.sf.net/u/<username>/code-<aircraft>/

And send the master branch where developments are located with:

git push --set-upstream origin master

The changes in the new repository will be visible via the web interface at https://sourceforge.net/u/<username>/code-<aircraft>/ci/master/tree/.

Sending external git repository changes into FGAddon

Note  Development scenario: You are an individual developer with FGAddon commit access and wish to transfer the commits in a remote git repository into FGAddon using a temporary local git repository.

Firstly clone the FGAddon aircraft into a local git-svn repository with:

git svn clone svn+ssh://<username>@svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/<aircraft>

This will create a new local git repository linked to FGAddon via git-svn. If the aircraft is new and not present in FGAddon, see the instructions for adding a new aircraft to FGAddon. Next, set up the remote git repository as a remote, and fetch it:

git remote add <name> <url>
git fetch

Where <url> is the URL of the remote git repository. Finally make an ordered list of all hashes of the commits to be sent into FGAddon, from earliest to latest, and cherry-pick them into the git-svn master branch:

git cherry-pick <commit hash 1>
git cherry-pick <commit hash 2>
git cherry-pick <commit hash 3>
...

Note that the git-svn local repository should only have a single master branch and only consist of cherry-picking. To see the changes queued for sending to FGAddon:

git log git-svn..HEAD
git diff git-svn..HEAD

Then to send the changes to FGAddon, firstly pull in any remote changes, and send the commits:

git svn rebase
git svn dcommit

The temporary local repository can then be deleted.

Connecting an existing git repository to FGAddon

Note  Development scenario: You are an individual developer or team leader with FGAddon commit access and wish to connect a pre-existing remote git repository with FGAddon to send all changes back to FGAddon.

If a remote git repository containing a developed aircraft already exists, it is possible to connect it to the remote FGAddon repository using the git-svn tools. The following uses the dedicated FGAddon branch technique. Firstly, set up the bridge to FGAddon using git-svn in the per-aircraft repository:

git svn init svn+ssh://<username>@svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/<aircraft>

Where <aircraft> is the aircraft directory name in FGAddon. Note that this step can be performed without commit access to FGAddon by using a read-only SVN URL instead, but then changes cannot be pushed back to FGAddon (dcommitting, as it is known in the git-svn terminology). However, this allows upstream FGAddon changes to be integrated into the remote git repository, thus making it easy to prepare changes for submission for FGAddon inclusion using patches sent to the mailing list or sent via other channels.

Now fetch the current state from the remote FGAddon repository:

git svn fetch

The downloaded SVN history is in the remote branch remotes/git-svn. To commit changes to SVN you need a local branch that tracks this remote branch. Create a local fgaddon branch that you will use to commit updates:

git branch fgaddon remotes/git-svn

After committing new stuff to the master branch, to push to FGAddon checkout the fgaddon branch and update it from SVN in case someone else has touched the aircraft in the remote FGAddon repository:

git checkout fgaddon
git svn rebase

Cherry-pick the new commits from master to fgaddon to preserve a linear history:

git cherry-pick <commit hash 1>
git cherry-pick <commit hash 2>
git cherry-pick <commit hash 3>
...

To see the changes queued for sending to FGAddon as either commits or a diff, type:

git log git-svn..HEAD
git diff git-svn..HEAD

If everything looks ok, dcommit the local commits on the fgaddon branch to send them to the remote FGAddon SVN repository:

git svn dcommit

Switch back to the master branch for local development:

git checkout master

To get changes from upstream you can either just download them with

git svn fetch

or download them and rebase your fgaddon branch onto them:

git checkout fgaddon
git svn rebase

Team development

Note  Development scenario: All members of the team are acting as gatekeepers, and all commits are made directly to FGAddon, either using svn or git-svn.

The simplest way to work as a team is for each developer to either have a svn copy of FGAddon or a git-svn copy of FGAddon, and everyone commits directly to FGAddon. Communication and coordination between the team members can be performed using a team leader organised SourceForge forum or using the FlightGear forum. In this scenario, the team needs to take the initiative and everyone apply for FGAddon commit access.

Private team development (git-svn)

Note  Development scenario: One team leader is acting as the gatekeeper on a private git repository hosted on the in-house SourceForge infrastructure, using git-svn to push a fgaddon branch to FGAddon, with team members committing directly to the private git repository or making merge requests from their fork of the private repository.

To keep everything in-house, the entire operation will be based on the official infrastructure and remote repositories under each user's SourceForge (SF) profile. Note to the team leader - you must keep your git-svn history linear (meaning that a dedicated FGAddon branch should be created and changes manually cherry-picked into this branch). In the following, the ornithopter aircraft will be used as an example.

The team

Firstly, the entire team should sign up for SourceForge accounts.

Team leader

Private repository set up

These steps are to be taken by the team leader. In your SourceForge user profile, set up a git repository with the label Ornithopter FGAddon git-svn repository and code path code-ornithopter. Then create a empty local git repository:

$ mkdir ornithopter
$ cd ornithopter
$ git init

Link the empty repository to the ornithopter aircraft directory in the remote FGAddon repository and pull it in with:

$ git svn init svn+ssh://<username>@svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/ornithopter
$ git svn fetch

Replace <username> with your SF user name. Set up a special git-svn branch for FGAddon gatekeeping and dcommitting changes back to the repository:

$ git branch fgaddon remotes/git-svn
$ git checkout fgaddon

And pull in the ornithopter from FGAddon:

$ git svn rebase

To see the current local git-svn repository setup, type:

$ git branch -vva
$ git remote -v
$ git svn info

Then return to the master branch:

$ git checkout master

Finally, set up the remote git repository as a remote:

$ git remote add origin ssh://<username>@git.code.sf.net/u/<username>/code-ornithopter/

And send the master branch to the remote git repository:

$ git push -u origin master

To see the new set up:

$ git branch -vva
$ git remote -v

The repository will be located at https://sourceforge.net/u/<username>/code-ornithopter/ci/master/tree/. Note that the git-svn information stored in the .git/svn directory will not be pushed to remote SoureForge repository, and therefore the link back to FGAddon will only be present in the local copy of the team leader. The git-svn link can be re-established at a later point if necessary.

Team setup

Set up a dedicated development team and grant them access to the git-svn repository.

Pushing to FGAddon

Committing to FGAddon is for the local git repository of the team leader. History must be linear in the fgaddon branch, so cherry-picking is the way to go. This is from the Individual developer (git-svn) section. In the local git repository, switch to the fgaddon branch:

git checkout fgaddon

Pull in any changes which have occurred in FGAddon:

git svn rebase

To see the commits in the master branch which are not in the fgaddon branch, type one of:

git log HEAD..master
git log HEAD..master --pretty=oneline

Manually select the commits to be sent to FGAddon and cherry-pick them:

git cherry-pick <commit hash 1>
git cherry-pick <commit hash 2>
git cherry-pick <commit hash 3>
...

Or to cherry-pick a range of commits:

git cherry-pick <commit hash 1>^..<commit hash 8>

Then check what is to be sent:

git log git-svn..HEAD
git diff git-svn..HEAD

Send the changes to FGAddon, send the git fgaddon branch changes to the remote git repository, and switch back to the master branch:

git svn dcommit
git push
git checkout master

Finally merge in the git svn commits with their new hashes from the fgaddon branch, and send it to the remote git repository:

git merge fgaddon
git push

Team members

Working with the repository

Each team member should make a clone of the private git repository:

$ git clone ssh://<username>@git.code.sf.net/u/<username_leader>/code-ornithopter/ ornithopter

Replace <username> with your SourceForge user name, and <username_leader> is the SourceForge user name of the team leader.

Forking and merge requests

Alternatively, each team member can fork the git repository under your SourceForge account:

  • Go to https://sourceforge.net/u/<username>/code-ornithopter/ci/master/tree/, where <username> is the SourceForge user name of the team leader.
  • Click on Fork.
  • Set the mount point to code-ornithopter and change the label as you wish.

Develop and push to your fork, then make merge requests by clicking on the Request Merge button.

References

  1. David Murr (Apr 9, 1996). FlightGear proposal 1.0: "A PROPOSAL FOR A NEW FLIGHT SIMULATOR - home built!@". Published on the rec.aviation.simulators newsgroup.
  2. David Murr (1996). FlightGear proposal 2.0: FLIGHT GEAR "This truly is as real as it gets!" - a proposal for a new flight simulator - REVISION 2.0.
  3. David Murr (Oct 29, 1996). FlightGear proposal 3.0: FLIGHT GEAR FLIGHT SIMULATOR, revision 3.0 - Wednesday, 10.30.96, "The future of flight simulation is here". Published on the flight-gear@infoplane.com mailing list.
  4. David Murr (Sep 11, 1998). FlightGear proposal 3.0.1: FLIGHT GEAR FLIGHT SIMULATOR, revision 3.0.1 - Friday, Sep.11.98, "The future of flight simulation is here".
  5. Curtis Olson (Sep 28, 2015). Re: A PROPOSAL FOR A NEW FLIGHT SIMULATOR - home built!@. Published on the FlightGear forum.
  6. James Turner (May 20, 2010). [Flightgear-devel] Re: Flightgear git repositories (was Re: GIT or CVS - Confusion) Published on the flightgear-devel mailing list.
  7. Cedric Sodhi (Oct 18, 2011) [Flightgear-devel] FGData Split Completed - a.k.a Life after the Split Published on the flightgear-devel mailing list.
  8. FlightGear Policy Document and Roadmap, draft document.
  9. GNU license compatibility list.
  10. Vim documentation