Contributing to training-labs scripts
=====================================

General
-------

Contributing code to training-labs scripts follows the usual OpenStack process
as described in `How To Contribute`__ in the OpenStack wiki.
Our `main blueprint`__ contains the usual links for blueprints, bugs, etc.

__ contribute_
.. _contribute: http://docs.openstack.org/infra/manual/developers.html

__ lp_
.. _lp: https://blueprints.launchpad.net/openstack-training-guides/+spec/openstack-training-labs

Getting started
---------------

The main script is osbash.sh. It will call libraries and other scripts to build
the training-labs setup. The setup can be customized in labs/config where all
scripts keep their configuration files.

Prerequisites
-------------

The labs scripts are designed to have minimal dependencies: bash and
`VirtualBox <https://www.virtualbox.org/>`_. To support OS X, we keep the
host-side scripts compatible with bash 3.2 (don't use features not present in
that somewhat dated version).

For testing the generated Windows batch scripts, any supported version of
Windows (Vista and later) will do. After having created the batch files using
osbash.sh, just copy the whole labs directory to Windows. If you don't have
access to that operating system, comparing the output in labs/wbatch will tell
you how your changes affect behavior on that platform.

Coding style
------------

We follow the conventions of other OpenStack projects. Since labs scripts are
currently all written in bash, the examples to follow are this project and
`devstack <http://devstack.org/>`_.

DevStack bash style guidelines can be found at the bottom of:
https://git.openstack.org/cgit/openstack-dev/devstack/blob/master/HACKING.rst

Structure
---------

**autostart**

osbash/wbatch copy shell scripts (\*.sh) into this directory to have them
automatically executed (and removed) upon boot.

**config**

Contains the configuration files for all the scripts. The setup can be customized here.

**img**

By default osbash will put into this directory its base disk images
(base-\*-<distro>.vdi), the VM export images (oslabs-<distro>.ova),
and all installation ISO images it may download.

**lib**

This directory contains bash libraries used by scripts.

**log**

Contains the log files written (and removed) by osbash/wbatch and
the scripts running within the VMs.

**scripts**

All scripts in this directory run within the VMs.

**wbatch**

Files in this directory are Windows batch files generated by osbash to
configure host-only networks, produce a base disk, and build OpenStack
training-labs VMs as configured when osbash created them.

Testing
-------

The labs scripts don't have automated tests yet. Patch submitters should be
aware of their responsibility for ensuring that their code works and can be
tested by reviewers.

Useful tools for checking scripts:

- `bashate <https://github.com/openstack-dev/bashate>`_ (must pass)
- `shellcheck <https://github.com/koalaman/shellcheck.git>`_ (optional)

Submitting patches
------------------

These documents will help you submit patches to OpenStack projects (including
this one):

- http://docs.openstack.org/infra/manual/developers.html#development-workflow
- https://wiki.openstack.org/wiki/GitCommitMessages

If you change the behavior of the scripts as documented in the training-guides,
add a DocImpact flag to alert the documentation team. For instance, add a line
like this to your commit message:

DocImpact new option added to osbash.sh

- https://wiki.openstack.org/wiki/Documentation/DocImpact

Reviewing
---------

Learn how to review (or what to expect when having your patches reviewed) here:
- http://docs.openstack.org/infra/manual/developers.html#development-workflow

TODO
----
Etherpad:
- https://etherpad.openstack.org/p/training-guides-developing-topics

Anything not covered here
-------------------------

Check README.md and get in touch with other scripts developers.