FlightGear Git: data developers: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
m (Update forum links)
m (→‎Authentication: fix typo)
Line 41: Line 41:
You should be suspicious if based on the printed progress you estimate the data download during the fetch will exceed 1GB (assuming the bundle is not terribly outdated).
You should be suspicious if based on the printed progress you estimate the data download during the fetch will exceed 1GB (assuming the bundle is not terribly outdated).


=== Authenticication ===
=== Authentication ===
In order to publish edits on Gitorious, you need to generate a secret key so you can be correctly identified.
In order to publish edits on Gitorious, you need to generate a secret key so you can be correctly identified.



Revision as of 12:35, 6 February 2014

Anyone contributing data to FlightGear, like aircraft models, dialogs or textures, is a data developer. This article helps those in setting up a correct workflow, to ease the inclusion of their work into the simulator.

Preparations

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

Cloning the repository

The first thing to do as a prospective developer is to register at Gitorious if you haven't 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 data repository. This clone is where you will be working in, without touching the main repository. To create a clone, navigate to the fgdata repository on https://gitorious.org/fg/ and click the Clone repository button. In general the default name is fine, but you can change it to whatever you like. Gitorious will now clone the data repository. Due to the size of our repository, this can take some time.

Obtaining the data

Before you can start editing, you first need to retrieve the data to your computer. There are two ways to do this. At the time of writing the data repository is over 5 GB. Continuing an interrupted cloning of a repository is not supported within Git. Therefore, if you have a slow or unstable connection to the internet, it is recommended to download the bundle.

For both approaches, Git must be installed. There is a lot of software available, but the following are often used:

Single clone

  1. Create a directory on your computer where you'll be storing the data.
  2. Change into that folder.
  3. Clone the repository with the following command. This will create a /fgdata subfolder and put all the contents of the repository in there.
    git clone git://gitorious.org/fg/fgdata.git

Bundle

For the FlightGear-data there is a git-bundle (snapshot) torrent (tracker; md5|sha1|sha512) available. This way you can resume interrupted downloads. After unpacking it only a comparatively small amount of data has to be transferred from the git server to synchronize your repository. See also the Develop sections in FlightGear Git on Windows.

  1. Create a directory on your computer where you'll be storing the data.
  2. Change into that folder.
  3. Do the following steps to extract the bundle and bring the repository up to date:
    git clone fgdata.bundle fgdata
    cd fgdata
    git checkout -b master-tmp
    git remote rm origin
    git remote add origin git://mapserver.flightgear.org/fgdata
    git fetch origin
    git branch --track master origin/master
    git checkout master
    git branch -D master-tmp

You should be suspicious if based on the printed progress you estimate the data download during the fetch will exceed 1GB (assuming the bundle is not terribly outdated).

Authentication

In order to publish edits on Gitorious, you need to generate a secret key so you can be correctly identified.

  1. Navigate to your newly created fgdata directory and run:
    ssh-keygen
  2. Enter the name of the file in which you prefer to save the key and press Enter.
  3. Enter your password/passphrase and press Enter. You'll have to do this twice.
  4. Your key is now being generated. Open the .pub file with an editor and copy the content.
  5. Visit your dashboard at Gitorious and navigate to "Manage SSH keys".
  6. Click the "Add SSH key" button and paste the content of the .pub file. Follow the instructions on the screen.
  7. Now run the following, again in your fgdata directory, with <url> as the line that you get by clicking SSH on your fgdata clone page at Gitorious (something like git@gitorious.org:~your/fg/yours-fgdata.git):
    git remote set-url origin <url>

Obtaining the simulator

In order to test your work, you'll need the FlightGear version that matches the data. Since FlightGear is under constant development, data from Git does not work with previous releases. Fortunately obtaining the latest development version of the simulator is fairly straightforward for most operating systems.

  • Mac: Download the .dmg
  • Windows: Download the 32-bits or 64-bits installer and follow its instructions. Let it install the binary into a clean directory.

Point $FG_ROOT to your freshly obtained fgdata directory. When using the launcher, this can be done on the first page, previous from the aircraft selection.

Making edits

It is recommended to split your new fgdata clone into separate local branches for your work. For instance, if you're working on the Boeing 747-400 and the aircraft reflection shader, you might create 2 branches named "747-400" and "reflect-shader". 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>

Publishing edits

To push local updates to your fgdata clone on Gitorious, 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 fgdata cloon Gitorious with the following command. Replace YourUID with your Gitorious account:
    git push git@gitorious.org:~YourUID/fg/YourUIDs-fgdata.git

Requesting edits to be merged

Creating a merge request at Gitorious.
  1. Click the "Request merge" button on your fgdata clone page. Loading the next page can take a while, as it will list all commits of the past years!
  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 to fgdata, target branch to master 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. You can find a list of people on the right side of the repository page.

Creating merge requests using this method literally means merging an entire branch into fgdata; 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.