FGAddon

From FlightGear wiki
Revision as of 17:52, 19 September 2015 by Bugman (talk | contribs) (→‎Aircraft development: Added an initial section about contacting the original aircraft authors.)
Jump to navigation Jump to search

The official FGAddon aircraft hangar is a version controlled repository, hosted on the SourceForge FlightGear infrastructure, for extra, optional 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 repository is for the day-to-day development of aircraft and 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 Some months ago, here, I asked to people to contact me in private in order to get commit access to the FGAddon repository.
— Clement de l'Hamaide (2014-12-16). Re: [Flightgear-devel] Wrong commits in FGAddon repository.
(powered by Instant-Cquotes)
Cquote2.png
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

Using FGAddon

Users

The following was taken from Aircraft are now hosted on SVN

Step 1: Preparation

Step 2: Get aircraft

Pick an aircraft (in this example the DR400-dauphin):

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

If you prefer to get all aircraft from the repo, use the following command. Beware that this means a huge download! Hundreds of aircrafts will be downloaded.

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

To obtain all of the FlightGear v3.6 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' development version, you can update your aircraft to the latest version using the command:

svn up

Aircraft development

Contact the original aircraft authors

The first step for developing and advancing the aircraft of the official FlightGear hangar is to make contact with the original aircraft authors. 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.

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.

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.

Cquote1.png About "how I decide who can or can't contribute" it's as simple as this: when someone contact me, I'm looking at who is this person, is it a long term contributor ? is it an active forum member ?
— Clement de l'Hamaide (2014-12-16). Re: [Flightgear-devel] Wrong commits in FGAddon repository.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png If he is not a long term contributor but an active forum member - "active" mean: a user who is member for long time (more than 3 months) and someone who posted more than 100 posts - I'm checking that this person is aware of how works FlightGear (by reading his posts) and his spirit (it's easy to know if someone is on the same wave or not by reading his posts) is in accordance with the FG spirit (I'm contributing to FlightGear and discussing with long term core dev since more than 4 years now so I can say that I know what is the spirit of FG)
— Clement de l'Hamaide (2014-12-16). Re: [Flightgear-devel] Wrong commits in FGAddon repository.
(powered by Instant-Cquotes)
Cquote2.png
Cquote1.png Also, I'm not the only one person who can give commit access, I give "admin" access to the FGAddon repo to 4 persons (Curt, Anders, Gijs, Torsten) so you can be sure that the FGAddon repo is not 'only in my hand' but also in the hand of other persons.
— Clement de l'Hamaide (2014-12-16). Re: [Flightgear-devel] Wrong commits in FGAddon repository.
(powered by Instant-Cquotes)
Cquote2.png

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 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>;

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 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 on 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 "FGAddon git-svn ornithopter".
  • Set the code path to "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>/ornithopter
$ git push -u origin master
$ git branch -vva
$ git remote -v

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

Team setup

Again this is for the team leader to perform. Firstly create a new development team, 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 "FGAddon git-svn ornithopter" git repository.
  • Click on "Admin - FGAddon git-svn ornithopter", 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 #Individual developer (git-svn). 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>/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>/ornithopter/ci/master/tree/, where <username> is the SourceForge user name of the team leader.
  • Click on "Fork".
  • Set the mount point to "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.