FGAddon

From FlightGear wiki
Revision as of 17:58, 22 September 2015 by Bugman (talk | contribs) (→‎Contact the original aircraft authors: Some editing and formatting.)
Jump to navigation Jump to search

The official FGAddon aircraft hangar is a version controlled repository, hosted on the SourceForge FlightGear infrastructure, used for the day-to-day development of aircraft. FGAddon is a Subversion version controlled repository. These are aircraft that are not part of the base package - the aircraft that are included in the base package are still kept in FGData repository - but are tagged with each stable release for the FlightGear download pages.

The FGAddon aircraft development repository should be considered unstable. If you are using a stable FlightGear release, it is best to obtain your aircraft with a matching version number from the FlightGear download pages. However as stable releases from FlightGear v3.4 onwards are tagged and present within the FGAddon repository, you may find that the Subversion tools are a convenient way to obtain individual aircraft or the entire official hangar of ~500 aircraft. Also, if you are using the lastest nightly releases or have compiled your own copies of FlightGear from the git version controlled repositories, using FGAddon allows you to update to the latest aircraft development versions.


Background

The Git/SVN repositories are intended more for developers, DIYers and people wanting to jump ahead and see the newest features. Most "average" users won't need to worry about which repository the aircraft are coming from.


Cquote1.png This is really important - we have had recurring issues with non-coders using CVS, Git and now Svn without thinking about the results. None of these systems are like Dropbox or and FTP server, and what you do with them has long-term consequences and potentially even implications for support the projects receives. I.e if we abuse the severs we get kicked off.
Cquote2.png
Cquote1.png I’m glad Clement is ensuring the quality of commits to the SVN repository is high, because unfortunately the Git repository suffered from that very badly. And in all these systems, there is often no ‘undo’ - once things are done, they are done forever, or require days of careful planning to make safe corrections.
Cquote2.png

Obtaining aircraft

Note  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.

If you have access to the SVN tools, the FGAddon version controlled repository can be a convenient way for obtaining aircraft for using within a specific FlightGear version directly from the official source. If you are using the nightly builds or a version controlled copy of FlightGear, you will probably wish to use the most up to date in-development versions of the aircraft to 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, you will need to install the Subversion tools:

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

Firstly, choose an aircraft to download. The DR400-dauphin will be used in this example. To download the aircraft for FlightGear v3.4.x, simply type:

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

To obtain the in-development version, type:

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

If you prefer to obtain all of the ~500 aircraft from the repository - beware that this will be a huge download of ~10G - use the following command:

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

If you are using a stable FlightGear release, for example FlightGear v3.6, to obtain all of the FGAddon aircraft to match your installed FlightGear version you can use:

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

Updates

If you have a checked out copy of the /trunk in-development version, you can update your aircraft to the latest version using the command:

svn up

Aircraft development

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, you could try to establish contact 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, you should first set up a SourceForge account. This will allow you to either directly commit to the FGAddon repository, if you have been granted commit access, or to work in as part of a SourceForge development team. The registration process is lightning quick and you'll have access to create your own SourceForge infrastructure and services in under a minute.

Commit Access

Before obtaining commit access, you should contact the original authors to determine if the aircraft is actively being developed. If so, the aircraft author will direct you as to how to proceed with development. Otherwise you will need to obtain FGAddon commit access to make the changes.

To obtain commit access, you should first demonstrate your capabilities. You should sign up for the FlightGear development mailing list and ask for help there. You should first provide your changes as patches. If these are not too large, they can be sent as attachments to the mailing list. For large patches, a code ticket can be created and the patch attached there, or the patch uploaded to a public server and a link sent in a development mailing list message.

If you are using a subversion command line client, you can create a patch by typing:

svn diff > my.patch

"my.patch" can be any file name. If you are using a git-svn command line client, type:

git diff > my.patch

Once 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, you can subscribe to the dedicated Flightgear FGAdddon commitlogs mailing list. One email is sent per commit, as the commit is made.


SourceForge development team

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.

Development 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 the team leader's SourceForge home page. 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 are simple:

  • On the team leader's 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.
  • Click on Save.

More details are given on the SourceForge Discussion documentation.

Development scenarios

Individual developer

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

If you are using the command line Subversion client, you can checkout an individual aircraft with:

svn co svn+ssh://<username>@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://<username>@svn.code.sf.net/p/flightgear/fgaddon/trunk flightgear-fgaddon

Once you have made you changes, commit these to the repository with

svn ci

You will need to write a detailed commit log message. When committing, it is best to make small modular commits so that each commit corresponds to a single purpose.


Individual developer (git-svn)

Note  Development scenario: You are an individual developer with FGAddon commit access and will use the git-svn tools.
Cquote1.png On a related note: for the aircraft maintainers that do like to work with

git it is not that hard to connect a per-aircraft git repository
(either your own or one split of from fgdata.git using the wiki
instructions) with the FGAddon SVN using the git-svn gateway.


— Anders Gidenstam (2014-11-15). Re: [Flightgear-devel] Write access policy for Subversion.
(powered by Instant-Cquotes)
Cquote2.png

The following description assumes you already have a single-aircraft git repository for your aircraft. It also describes a somewhat more complicated pull/push to SVN than necessary that I use since I want my private development history to be unaffected by whatever strangeness that may happen in fgdata/FGAddon.

Step 1

Setup git-svn to FGAddon in your per-aircraft repository:

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

Note: This step can be done even you don't have commit access to FGAddon by using a read-only SVN URL instead. Obviously, you cannot push (dcommit) changes back to FGAddon in that case. However, git makes it possible to keep your own work under version control and integrate it with changes from upstream, thus making it easy to prepare your work for submission for inclusion in FGAddon via the mailing list or other channels.

Step 2

Fetch its current state from FGAddon/SVN:

% git svn fetch

Step 3

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. You could use this branch as your new master branch, but I would not do this since the branch used to pull/push from/to SVN will be rebased on SVN updates and gets ugly SVN user names etc. in the commits. However, point 4. below would be much shorter if you do all your development directly on such a local branch that tracks the SVN interface branch.

% git branch fgaddon remotes/git-svn

Step 4

When you have committed new stuff on your master branch that you want to push to FGAddon, you checkout your FGAddon branch:

% git checkout FGAddon

Update it from SVN in case someone else has touched your aircraft in the FGAddon SVN.

% git svn rebase

Cherry-pick your new stuff from master to FGAddon:

% git cherry-pick <commit id>

Commit the local commits on your FGAddon branch to the FGAddon SVN:

% git svn dcommit

Checkout your master branch again for local development:

% git checkout master

Step 5

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

If you keep your local master separate from FGAddon you would need to cherry-pick upstream updates you want to your master branch. These days I always use git-svn rather than the ordinary SVN tools when working with SVN repositories. It is just so much nicer to me.

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.

This 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 may be best on the FlightGear forum. In this scenario, the team needs to take the initiative and apply for everyone to be granted 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.

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 pure git repository:

  • Go to Personal tools -> Add Tools.
  • Click to install -> git.
  • Set label to Ornithopter FGAddon git-svn repository.
  • Set the code path to code-ornithopter.

Then create a local git repository:

$ mkdir ornithopter
$ cd ornithopter
$ git init

Set up a special git-svn branch for FGAddon gatekeeping and dcommitting (pushing):

$ git svn init svn+ssh://<username>@svn.code.sf.net/p/flightgear/fgaddon/trunk/Aircraft/ornithopter
$ git svn fetch
$ git branch fgaddon remotes/git-svn
$ git checkout fgaddon
$ git svn rebase
$ git branch -vva
$ git remote -v
$ git svn info 
$ git checkout master

Replace <username> with your SF user name. Finally, set up the git repository as a remote and push:

$ git remote add origin ssh://<username>@git.code.sf.net/u/<username>/code-ornithopter
$ git push -u origin master
$ 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

Again this is for the team leader to perform. Firstly create a new dedicated development team, here called "ornithopter", under your user profile:

  • 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 your team members.

Then set up the your development group with your team mates:

  • Go to the Ornithopter FGAddon git-svn repository git repository.
  • Click on Admin - Ornithopter FGAddon git-svn repository, then select Permissions.
  • In the Write section, remove Developer and add ornithopter.
  • Click on Save.
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 git repository, type:

$ git checkout fgaddon
$ git svn rebase
$ git cherry-pick <commit id>
$ git svn dcommit
$ git checkout master

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.