Guidelines
==========

.. toctree::
   :maxdepth: 1

   guidelines/conventions


Version Control
---------------

Everything must be in version control before being used on production systems.
In particular, scripts and other software, SPEC files for packages, relevant
documentation, Puppet code, etc.

Git Hooks
---------

`This repository <https://gitern.psi.ch/linux-infra-software/githooks>`_ provides a pre-commit git hook that checks code compliance to different standards.

Hiera Code
----------

The naming of the variables inside Hiera depends on the scope usage of the variables.

The variables beeing used only inside one specific class
will be named ``base_class_name::variable`` where ``base_class_name`` is the last part of class name, without the part before the last ``::`` separator.
Eg. the ``permit_root_login`` variable for the ``profile::ssh_server`` class will be named ``ssh_server::permit_root_login``.

When a variable is shared between a client and a server, we will prepend the variable name with the service name.
Eg. the ``grid_name`` parameter for ganglia service, used inside both client and server configuration, will be named ``ganglia::grid_name``.

*Note:* this could potentially bring to conflicts, if we want to specify hiera values to be used both inside roles and profiles with the same name.
Do we want that?


Code Reviews
------------

All code must be reviewed by at least one other team member with write access to
the repository before pushing it. This will help keep the style consistent and
increase familiarity with the code base.


External Code
-------------

Although the installation infrastructure makes large usage of external code the system
has to avoid as much as possible dependency from external services availability.
A WAN outage or a remote http server failure should not influence the installation system.
For this reason, all the external code is mirrored internally in specific git repositories.

Servers and services
--------------------

Every server should support exactly one service, e.g. Puppet, or FTP. This makes
the services more independent (e.g. for downtimes), simplifies the structure of
the corresponding Puppet code, makes it easier to reason about the environment,
and prevents conflicts regarding certain configuration settings.


Development Workflow
--------------------

The general inspiration comes from `this post
<http://nvie.com/posts/a-successful-git-branching-model/>`_.

Regarding the puppet code this is more detailed description of our current
workflow:
