Introduction

This tutorial describes how to modify an existing tutorial or add a new tutorial.

Tutorial source code

All tutorials exist in a GitHub repository: https://github.com/osrf/gazebo_tutorials.

This repository contains a manifest.xml that holds meta-information about the tutorials, and a set of directories that hold the tutorial contents.

All changes to the set of tutorials will use the pull-request feature on the GitHub site.

Modify a tutorial

Follow these steps to change an existing tutorial.

1. Click the Edit button located at the top-right of the tutorial you want to modify.

2. This will bring you to the tutorial source on GitHub.

3. Click the Edit button on the file (see GitHub help page).

4. Make your changes to the file using Markdown syntax.

5. Choose to create a new branch and start a pull request.

6. Type a commit message to describe your changes and propose file change.

Create a new tutorial

The steps for creating a new tutorial are similar to those for modifying a tutorial.

1. Fork the gazebo_tutorials repository.

2. Add a new top-level directory to hold the contents of your tutorial.

3. Populate the new directory with a text file formated using markdown and any other supporting material.

4. Add a new <tutorial>...</tutorial> block to manifest.xml

   1. Make sure the ref attribute of the <tutorial> is unique and contains no special characters.
   2. The <description> should be very short.

   3. Set the minimum and maximum version of gazebo for which the specified markdown file is applicable. For example:

      1. <markdown version="1.9">...: Only version 1.9
      2. <markdown version="1.9+">...: All versions 1.9 and above
      3. <markdown version="1.9-2.0">...: All versions between 1.9 and 2.0, inclusive.

   4. It is possible to have multiple markdown files for different versions of Gazebo. Just add multiple <markdown> tags that reference different markdown files.

5. Add the new tutorial to an existing <category>, located toward the bottom of the manifest.xml file. Create a new category if you tutorial does not belong in an existing category.

6. Create a pull-request back to the gazebo_tutorials repository.

7. Your pull-request will be reviewed, during which time you may be asked to make changes.

8. Once accepted, your pull-request will be merged into the repository. Your changes should appear on the main gazebo website in a few minutes.

View a tutorial branch

During development of new tutorials, or when modifying existing tutorials, it is often desirable to visualize the tutorial before submitting a pull-request. Tutorials from a specific branch of the gazebo_tutorials repository may be visualized on http://gazebosim.org/tutorials using the branch=<branch_name> URL parameter.

For example, let us suppose you have made modifications to the install tutorial in a branch called my_install. Once this branch has been pushed to GitHub, you may visualize your work with http://gazebosim.org/tutorials?tut=install_ubuntu&branch=my_install.