Best Practices for Contributing QWG Templates

Table of Contents

1. Template names and namespaces
2. Variables
3. Coding Style

Template names and namespaces

QWG templates describe how to configure machines running a certain set of services. A machine includes everything from hardware configuration to the services run on the machines, including the OS and RPMs used. A service is any part of the configuration that may described as a unit and that may be used by other services. It is not related to a particular daemon/service. QWG templates distinguish between two types of services:

• Low-level services: services whose configuration don't rely on another services. In the gLite templates, they are found under the common namespace (one specific namespace per service).
• High-level services: services who configuration involves the configuration of underlying (low-level) services. In gLite templates, they are found under glite (or lcg for legacy services) namespace, with one namespace per service. In standard templates, they are found under the features namespace, with one namespace per service.

In QWG templates, there are a few conventions on template names:

• For templates configuring a low-level service, the main template describing the configuration must be called config.tpl.
• For templates configuring a high-level service, the main template describing the configuration must be called service.tpl and mainly includes the configuration template (typically config.tpl) of every low-level service required. A service config.tpl must also exist to do the configuration specific to the high-level service but is not intended to be called directly.
• Some services may require an early configuration step to be done generally during the OS configuration. When this is the case, the template used for this early configuration step must be called init.tpl.
• RPMS required by a particular service or OS component must be described in a dedicated template. The recommended name of this template varies depending whether all the RPMs are architecture independent or not.
  • If the RPM list contains only architecture independent RPMs or if there is not and will not be any support for multiple architectures, the template must be called rpms.tpl.
  • If the RPM list has some dependencies on the architecture, the template must called config.tpl and sits into a rpms namespace under the service namespace. Generally the rpms namespace contains one sub-namespace per architecture (whose name is the architecture) and this sub-namespace contains a template config.tpl listing the architecture-specific RPM required by the service. This architecture-specific config.tpl is not intended to be called directly but must be included by the main (architecture-independent) config.tpl.

Variables

QWG templates make an intensive use of variable. To avoid name collisions, the following convention has been established:

• These variables being global, their name must be in uppercase.
• The variable name must start with the service name followed by an _ (underscore) they apply to. For historical reasons, some variables don't adhere to this convention but new variables must. When contributing to the configuration of an existing service, please adhere to the name prefix already used.
• The variable name prefix used must be consistent across the whole service configuration
• Some examples: DPM, LCGCE, CREAM, NFS...

Some variables have a specific purpose and can be found in many different services:

• xxx_CONFIG_SITE: the value is a template name describing the site-specific configuration of service. For historical reasons, the variable name suffix is CONFIG_SITE and not SITE_CONFIG. Please adhere to this convention.

Variables intended to be customized by sites must be documented in the Documentation section of this wiki.

Coding Style

It is very important for a template to be well presented so that others can understand it and contribute to it. QWG templates are designed to allow many people to contribute to the standard set of templates. There is not a very strict coding style but a few recommandations:

1. If you contribute to an existing template, except if the template doesn't adhere to a minimum standard of readability, try to adhere to the convention used in the initial template.
2. Use spaces rather than tabs as tabs are not displayed the same way in all editors. Use the same tab identation that is already used in an existing template. Else the typical recommendation is 2 spaces.
3. Ident properly list and nlist, with one element per line, each line (including the last one) followed by a ,.
4. Prefer meaningful variable names to long comments
5. Write the minimum set of comments required for others to understand your implementation when there is some hidden complexity or an external constraint like a bug. In case something is a workaround for a bug, please put a reference to the bug if available in a publically available bug tracker.