FlightGear Git: core developers

From FlightGear wiki
Jump to navigation Jump to search

Anyone contributing to the core of FlightGear, like C and C++ code, is a core developer. This article helps those in setting up a correct workflow, to ease the inclusion of their work into the simulator.

Preparations

The in this section described steps are only required once, at the initialization of your development environment.

Cloning the repositories

The first thing to do as a prospective developer is to register at SourceForge if you have not already done so. This will enable you to publish your edits and have them incorporated into the main project.

After logging in, you can create a personal "clone" of the various FlightGear repositories. These clones are where you will be working in, without touching the main repositories. To create a clone, navigate to the respective repository on http://sourceforge.net/p/flightgear/_list/git and click the Fork button. In general the default name is fine, but you can change it to whatever you like. SourceForge will now clone the repository. Depending on the size of the repository (especially fgdata is a large one), this can take some time.

Obtaining the source

Before you can start editing, you first need to retrieve the source code to your computer. For FlightGear you will need SimGear, FlightGear and fgdata. The first two are covered by this article, the latter is explained in FlightGear Git: data developers#Obtaining the data.

  1. Create a directory on your computer where you'll be storing the source code.
  2. Change into that folder.
  3. Clone the repositories with the following commands. This will create subfolders and put all the contents of the repositories in there.
    git clone git://git.code.sf.net/p/flightgear/flightgear
    git clone git://git.code.sf.net/p/flightgear/simgear

Building the simulator

Now that you've set up a development environment and obtained source and data, the next step is to build FlightGear from that source. There are several articles that can help you there. They are all listed at Building FlightGear.

Making edits

It is recommended to split your new clones into separate local branches for your work. For instance, if you're working on a new radio code and performance improvements, you might create two branches named "radio" and "performance". To do this, run the following commands:

git checkout master
git checkout -b <branch name>

Then you can make your changes to the new local branch(es), which will make merge requests easier for both yourself and committers. To switch in between branches, simply use

git checkout <branch name>

Re-build FlightGear (and if neccessarily SimGear) after making changes, to confirm that everything works as expected.

Publishing edits

To push local updates to your clones on SourceForge, perform the following steps:

  1. Switch to the branch that contains your edits:
    git checkout <branch name>
  2. List all the changed files:
    git status -- .
  3. Now it's time to commit the changed files.
    • If you want to commit all changed files, run the following and type your commit message.
      git commit -a
    • If you only want to commit a selection of files, run the following:
      git add <path/to/file> (for single files)
      git add --all <path/to/folder> (to add all files within a certain folder)
      git rm <path/to/file> (to remove files that you've removed)
    Followed by
    git commit -m "<commit message>"
  4. Check if everything went fine, by loading Gitk:
    gitk
  5. Finally, push the commit to your clone on SourceForge with the following command. Replace YourUID with your SourceForge account and YourClone with the name of your clone:
    git push ssh://YourUID@git.code.sf.net/u/YourUID/YourClone

Requesting edits to be merged

  1. Click the "Request merge" button on your clone page.
  2. Once again write a short summary (could be the same as used with git commit), but this time, also write an explanation of your merge request (what does it do?). Make sure you set the target repository correctly, target branch to next and source branch to the local branch with your updates.
  3. Tick the box in front of your commit and click the "Create merge request" button.
  4. Everyone can see the pending request, but in order to make sure that your request gets looked at, you may contact a contributor.

Creating merge requests using this method literally means merging an entire branch into the main repository; this may not be desirable for some situations, such as small changes that only require one little commit. There's a neat method to only push certain commits to a merge request discussed by Anders Gidenstam on the FlightGear Forums.