Development workflow

Work in progress This article or section will be worked on in the upcoming hours or days. See history for the latest developments.

This page is meant to be a high-level introduction to the development workflow of FlightGear, that is, the process developers follow to contribute their work to the project.

The big picture

Everything is stored in several Git repositories (collection of files) on SourceForge. You can find a list of them in the FlightGear Git page.

Only a handful of developers have commit access, that is, the right to make changes to those repositories without prior approval. This is done to ensure that only people showing a good, consistent contribution track record and good judgement are able to perform such modifications unsupervised. For this reason, once a developer contributes some work, it will need to be staged for approval by another contributor having commit access.

Life of a patch

The contribution process can be divided in the following phases.

1. Fork the repositories you would like to contribute to. In this context, a fork is a personal copy of the original repository created for your proposed modifications until they are accepted into the project. It is created on the same infrastructure as the official repositories.
2. Clone the forks of the repositories. A clone is a local copy of a fork, kept in sync with changes in the offical repositories. You will need to clone the fork repository to your local machine which create a copy of its data to your computer. This will establish the fork as a remote repository named "origin"
3. Establish the original repositories as an "upstream" remote. Updates in the upstream remote can be pulled into your local clone.
4. Perform the desired modifications locally in a branch and push them to your clone.
5. When you are ready to get your work accepted, submit a merge request. A developer will check your contribution before merging it into the project repositories. Fix any issues that are found during the review.
6. Once your work is included,
   1. monitor the build server, the mailing lists and the forum to check for bugs you might have inadvertently introduced.
   2. pull the changes from upstream, remove your local branch and push to origin.

When is a Fork needed and when it's not:

If you are contributing changes to Flightgear, you need a fork of the official Flightgear reposotories on SourceForge.

If you are not contributing, and only wish to build flightgear, you do not need a fork. Instead, you should simply clone the official Flightgear Repositories as origin. In this case, an upstream remote connection is unnecessary.

Specific Steps

1. Create a ED25519 or ECDSA key for use with Sourceforge
2. Update Sourceforge with the contents of your public key file.
3. Create Sourceforge forks of flightgear-flightgear and flightgear-simgear
4. Create a working directory for your work, possibly an IDE project directory
5. Clone your forks https://git.code.sf.net/p/flightgear/simgear flightgear-simgear and https://git.code.sf.net/p/flightgear/flightgear flightgear-flightgear
6. Establish upstream remote
7. Create a branch or branches for your work
8. Discuss changes on flightgear-devel mailing list
9. Request Merge when ready
10. Pull changes from upstream next
11. Wait for bugs to appear, revise your branch and Merge again
12. Later, Optionally, Remove local changes branch and push to origin

Scenery and aircraft contributions

Due (mostly) to their file size, scenery and aircraft are stored using different file management systems and, thus, do not follow the process outlined in this article.

• Scenery contributions should be submitted to the FlightGear Scenery Database.
• Aircraft contributors should follow the instructions given in FGAddon.

Tips

• If you need to take a design decision or want to get some preliminary feedback, ask people on the flightgear-devel@lists.sourceforge.net mailing list and/or on the forum.

References