Software engineering and QA

Transcription

1 IDM UID 2NRS2K VERSION CREATED ON / VERSION / STATUS 11 Feb 2011 / 2.1 / APPROVED EXTERNAL REFERENCE How To Software engineering and QA This document describes general rules, practices and recommendations for software engineering in scope of ITER CODAC activities. Approval Process Name Action Affiliation Author Stepanov D. 11-Feb-2011:signed IO/DG/DIP/CHD/CIT/CODAC CoAuthor Reviewers Klotz W.- D. Wallander A. 21-Feb-2011:recommended 14-Feb-2011:recommended Approver Bora D. 23-Feb-2011:approved IO/DG/DIP/CHD Document Security: level 1 (IO unclassified) RO: Di Maio Franck Read Access IO/DG/DIP/CHD/CIT IO/DG/DIP/CHD/CIT/CODAC AD: ITER, AD: External Collaborators, AD: Section - CODAC, project administrator, RO PDF generated on 23-Feb-2011

2 Change Log Version Latest Status Date Description of Change v2.1 Approved 11 Feb 2011 Minor corrections after the internal and external reviews. v2.0 Signed 10 Jan 2011 Updated for the inclusion into the PCDH v6. v1.0 Approved 22 Jul 2009 PDF generated on 23-Feb-2011

3 Table of Contents 1 Introduction Purpose PCDH Context Scope Definitions and Abbreviations References Software Engineering Recommended Software Integrated Development Environment (IDE) Software Support Infrastructure Software repository Issue tracking system Reference development server Dedicated development machines Nightly-build server File server Software distribution server Infrastructure support servers Developers website area User accounts Naming and Coding Conventions File naming and contents Standard headers Java coding conventions C coding conventions Python coding conventions SQL coding conventions XML coding conventions Software Licensing Policy Packaging Guidelines Packages classification Packages naming convention (regular case) Packages naming convention (advanced case) Packages breakdown guidelines Packaging other than RPM Distribution Guidelines Using an RPM / YUM repository Using Red Hat Network Satellite Using RPMs and self-extracting archives Using plain tarballs Using OS-bundled distribution Software Quality Assurance...15 Page 1 of 28

4 3.1 Roles and Responsibilities Roles Responsibility chart Configuration control board Quality Control Issue tracking QA records Version Control Storage principles Top level breakdown Software units Principal operations on a repository Version control systems other than Subversion Software Life Cycle Parallel product versions Environment setup Development Testing Documenting Release cutting Porting and packaging Release User support Documentation Guidelines Documents prepared by developers Generated documentation Third party documentation...28 Page 2 of 28

5 1 Introduction 1.1 Purpose This document describes general rules, practices and recommendations for software engineering in scope of ITER CODAC activities. 1.2 PCDH Context The Plant Control Design Handbook (PCDH) [RD1] defines methodology, standards, specifications and interfaces applicable to ITER Plant Systems instrumentation and control (I&C) system life cycle. I&C standards are essential for ITER to: Integrate all plant systems into one integrated control system; Maintain all plant systems after delivery acceptance; Contain cost by economy of scale. PCDH comprises a core document which presents the plant system I&C life cycle and recaps the main rules to be applied to the plant system I&Cs for conventional controls, interlocks and safety controls. Some I&C topics will be explained in greater detail in dedicated documents associated with PCDH as presented on Figure 1-1. This document is one of them. Its objective is to describe the software engineering and quality assurance (QA) in more detail. 1.3 Scope Figure 1-1: PCDH documentation structure This document defines only general topics. Particular projects within CODAC (such as CODAC Core System) may go into further details on their particular subjects. PLC-specific development is described in a separate handbook ([RD2]). The content of this document applies both to the plant system specific development (PBS XX) and to the CODAC internal development (PBS 45). This document is equally applicable to development of interlock Page 3 of 28

6 systems (PBS 46) and plasma control algorithms (PBS 47). The safety part (PBS 48) is not addressed yet. Software for control system elements qualified as COTS devices does not have to follow these rules and should follow engineering and QA guidelines of their respective manufacturers and / or maintainers instead. 1.4 Definitions and Abbreviations 24/7 24 hours a day, 7 days a week CIS Central Interlock System CODAC COntrol, Data Access and Communication COTS Commercial Off-The-Shelf CR Carriage Return CSS Central Safety System DHCP Dynamic Host Configuration Protocol DNS Domain Name System DVD Digital Video Disc EOL End-Of-Line EPICS Experimental Physics and Industrial Control System GNU GNU's Not UNIX GPG GNU Privacy Guard I&C Instrumentation and Control IDE Integrated Development Environment IDM ITER Document Management LDAP Lightweight Directory Access Protocol LF Line Feed NFS Network File System NTP Network Time Protocol OS Operating System PBS Plant Breakdown Structure PCDH Plant Control Design Handbook PDF Portable Document Format PLC Programmable Logic Controller PS Plant System PSH Plant System Host QA Quality Assurance QC Quality Control R&D Research and Development RD Reference Document RHEL Red Hat Enterprise Linux RO Responsible Officer RPM Red Hat Package Manager S-DDD Software Design Description Document SCCB Software Configuration Control Board SQL Structured Query Language SRS Software Requirements Specification STP Software Test Plan STR Software Test Report tar tape archive UNIX UNiplexed Information and Computing System URI Uniform Resource Identifier URL Uniform Resource Locator UTF-8 Unicode Transformation Format 8-bit W3C World Wide Web Consortium XML extensible Mark-up Language YUM Yellowdog Updater, Modified 1.5 References [RD1] Table 1-1: Abbreviations used Plant Control Design Handbook (27LH2V v6.1) Page 4 of 28

7 [RD2] PLC Software Engineering Handbook (3QPL4H v1.3), 09 Feb 2011 [RD3] [RD4] Version Control with Subversion ( Code Conventions for the Java Programming Language ( 20 Apr 1999 [RD5] Linux Kernel Coding Style ( 13 Jul 2007 [RD6] Style Guide for Python Code ( 28 Nov 2010 [RD7] XML Schema Part 2: Datatypes Second Edition ( 28 Oct 2004 [RD8] CODAC Software Licensing (332QB4 v1.0), 14 Jan 2010 [RD9] Maximum RPM ( [RD10] How to setup your own package repository ( [RD11] Apache Maven Project / Introduction to the Standard Directory Layout ( [RD12] ITER Plugin for Maven (32Z6UL v1.0), 09 Feb 2010 [RD13] Bugzilla-tutorial (33KAC4 v1.0), 09 Feb 2010 [RD14] CODAC Core System Support Procedures (34EHTM v1.3), 05 May 2010 [RD15] CODAC Core System Documentation template (33ZDG3) Page 5 of 28

8 2 Software Engineering 2.1 Recommended Software The software listed below should be considered as preferred when choosing the environment for a new project within the CODAC framework. Deviations from this list shall be discussed with the ITER Organization. Name Usage Ref Operating systems 1 RHEL x86_64 Base development and target platform ref 2 Red Hat Network Satellite Software distribution system ref Programming languages 3 Java General purpose programming language for application development 4 C Language used for specific low-level tasks (such as drivers development) 5 Python Main integration language (scripts, services, prototypes, ) 6 Shell (bash) Linux system scripts 7 SQL / PL/SQL Database programming language 8 XML / XSD / XSLT Structured descriptions of data in text 9 FBD, LD, ST, IL, SFC PLC programming languages Development instruments 10 Eclipse / RCP Java framework for application development ref 11 Apache Subversion Version control system ref 12 Bugzilla Bug tracking system ref 13 Hudson Build integration server ref 14 Altova XMLSpy XML / XSD editing and documenting tool ref 15 Apache Maven Build integration tool ref 16 Apache Tomcat Web application deployment platform ref Databases 17 PostgreSQL Databases for small / distributable data sets ref 18 Microsoft SQL Server Databases for CODAC central systems ref Specific frameworks 19 EPICS Distributed control systems framework ref 20 Control System Studio Control systems application framework ref 21 Siemens SIMATIC STEP 7 Siemens PLC programming environment ref Table 2-1: Recommended software Versions of these programs are the subject of controlled evolution along with the development of CODAC and are not communicated here. 2.2 Integrated Development Environment (IDE) The principal IDE solution for software development is Eclipse IDE. There is an ongoing activity to provide a special Eclipse IDE setup tailored for CODAC-oriented software development. 2.3 Software Support Infrastructure In order to support the development process it is recommended that a number of machines (physical or virtual) serving different functions are installed. They are listed below. 1. Software repository; 2. Issue tracking system; 3. Reference development server; 4. Dedicated development machines; 5. Nightly-build server; 6. File server; 7. Software distribution server; 8. Infrastructure support servers; 9. Developers website area. Depending on nature of work, some of these machines may be missing or, on the contrary, replicated in multiple copies. The setup of the environment shall be complementary, not exclusive, so that the whole setup can be replicated on a reduced set of servers in order to enable completely autonomous development. The setup technique is optionally a kick-start installation of the CODAC default Linux image plus a script-driven installation of the particular environment on top of the OS. Page 6 of 28

9 ITER Organization has this setup fully implemented and available 24/7. I&C designers and software programmers are invited to use this central infrastructure with their projects Software repository The software repository is a key instrument for software development. It keeps track of all the versions of the software produced and allows a consistent snapshot from any given time in the past to be restored. In the CODAC environment the repository is organized with a help of Subversion software. For more details on repository organization see section Issue tracking system An issue tracking system serves as a peer management tool for software development. It allows tracking of bugs and features, assigning priorities and responsible persons, discussion and following up on implementation progress. In the CODAC environment, Bugzilla software is used as an issue tracking system. Several software products (such as the CODAC Core System) together with their associated release planning may be introduced in it. Normally, some sort of cross-references exists between a software repository and an issue tracking system. For instance, when something is committed in the repository it often carries the corresponding issue s identifiers, whereas comments in the issue tracking system record the history of commits made in relation to the issue in the repository. Software exists which allows the automation of these cross-references to a certain extent Reference development server The reference development server provides a 24/7 environment for general development and testing. It comprises two principal parts: 1) Current OS installation with rich development-specific profile (compilers, debuggers, profilers, ); 2) The latest nightly build of the CODAC software installed. The software shall be used for reference purposes and will not be available for direct modification by developers. The primary use of this machine is to serve as a reference development environment, to allow rapid consultation of the latest state of CODAC software without any installation work, to be able to write and / or run some simple occasional tests against this software and to consult the latest source codes and test results. This machine is supposed to be used by developers on a daily basis; no resource-intensive tasks should be run on it Dedicated development machines Certain development tasks and activities may require full control over the machine or its development environment. Typically these include: The need to have administrator privileges on the machine; Installation and development against the new, experimental software; Particular resource-intensive activities, such as regression tests execution; Feature-oriented development, such as integration with databases; Connectivity with specific peripheral devices, such as fast controller boards; Driver development; Development and testing of installation procedures (e.g., RPM packaging); Release preparation activities (freezing, packaging, installing, verifying, ). For such tasks, dedicated development machines can be allocated (either virtual or physical). The name of the machine may reflect its purpose Nightly-build server The nightly-build server is used to compile the latest snapshots of the software and to perform regression testing on them. The set of packages installed on the nightly-build machine is identical to the one of the development server. The nightly-build machine is set up so that it holds: Page 7 of 28

10 1) Complete source tree of the units being developed; 2) Set of tests to be run against, including control scripts; 3) Current canonical outputs. Canonical outputs of the unit are those which have been approved after thorough verification steps and then saved in the software repository. The machine is set up in the way that, first, once per night the latest source code (*/trunk/) is checked out from the Subversion, then the incremental build is done (only compiling changed files) and then the entire set of existing regression tests is executed. The output of the tests is stored separately for each day and kept in such a way that they are easily accessible until the next major release is issued. Once a week the compilation environment is cleaned of binaries and the fresh build is made, followed by the same regression testing. This allows errors introduced in the build procedure itself to be caught. The entire compilation and testing process is executed under a dedicated account (e.g., builder), so that ordinary developers have no possibility to intervene in, or impede the testing process. They should still have the possibility to compile and test in their own home folders File server Because the development cluster has multiple machines installed, it needs a simple and practical file exchange facility and a place dedicated for storing common files. The file server fulfills this role. Typically, the following are stored there: Snapshot of the latest source code from the software repository (used for quick browsing / reference); Packaged and unpackaged products of previous public releases, allowing execution or to be compiled against (used for user support and bug hunting); Binary files used for compilation but which are not part of the software repository; Any sort of documentation or support files deemed necessary for developers but which are not a part of released products; Area for rapid file exchange between machines in the same network; Users home folders. The shared area shall be mounted via NFS at the same mount points for all computers concerned. Selected subfolders of the shared space may be mounted read-write or read-only on different NFS client machines, depending on their needs. As a general rule, to prevent accidental data damage, no write access should be provided unless required for work procedures Software distribution server The software distribution server contains packaged software for all supported releases and allows downloading and installing this software. It can be used both for CODAC clients and for internal installations. In the CODAC environment the Red Hat Network Satellite software is used to organize software distribution. Every user performing installation from this server has to be registered with the server. Apart from the public releases, the distribution server facilitates distribution of the software built everyday by publishing its packages on a daily basis and allowing daily updates from local machines Infrastructure support servers Infrastructure support servers are not directly visible to software developers and are used to support various system administration tasks on the development cluster. Typically these tasks include: User and group management (e.g., LDAP); Remote access support (firewalls and remote connection services, such as NoMachine NX); Name resolution services (DNS, DHCP, ); Time synchronization service (NTP); Backup and mirroring systems; Servers and networks monitoring systems; Web server for development web area. Page 8 of 28

11 2.3.9 Developers website area The developers website serves as an area to centralize all development activities. This website usually hosts or provides references to the following information: List of projects being worked on, with the associated tasks and progress tracking; Entry point to the software repository; Entry point to the issue tracking system; Entry point to the distribution server; Developers discussion boards; Description of the development environment (servers, access, how-to s, ); Documentation for various software packages User accounts As a general rule, every user in the development environment obtains and uses his or her own user account. Use of shared accounts should be kept to the absolute minimum. By its nature, the development and testing process implies some risk of improper software behavior or data loss. A proper access policy shall be put in place in order to minimize the risk of data corruption across the user accounts. If there is a need to do development or testing under the super-user account, it is recommended to set up a dedicated machine for that purpose. All the software delivered to end user shall run under non-privileged user accounts unless it requires superuser rights for some specific, well defined purpose. 2.4 Naming and Coding Conventions File naming and contents File naming conventions are largely driven by particular domains of use and follow their established practices. In the case that there is no particular rule, two different schemes are proposed: 1) All words are capitalized, underscore _ is used as a word separator (example: CODAC_Core_System_User_Manual.pdf ); 2) All words are lowercase, hyphen - is used as a word separator (example: privilegeseparation.sh ). Special characters and whitespaces are generally not recommended, as they cause various problems in processing. Capital letters are allowed; however, software shall not be case sensitive to file names (this will cause collisions on Windows). File extensions shall be provided in order for the file to be properly associated with application software. In the case that several extensions exist for the same file type (e.g., html and htm ), the most common one should be used. File extensions should be lowercase. Encoding of files shall be UTF-8 unless needed otherwise for a particular purpose. Line endings (EOL characters) are not standardized and can be either UNIX style (LF) or Windows style (CR+LF), with preference given to UNIX style. All other styles (e.g., CR of Mac OS) shall be avoided; mixture of different EOL styles in the same file shall be avoided as well. Preference shall be given to software capable of transparent processing of all kinds of line endings. Folder (file directories) names shall follow the same rules as for files. In the UNIX tradition, folders often have short simplistic lowercase name (e.g., src or doc ) Standard headers As far as practicable, every file created by the ITER Organization or for the ITER Organization shall carry identification information. For text files (source codes, text documentation, etc) the following standard header shall be used: $HeadURL$ $Id$ Project : <Project name> Page 9 of 28

12 Description Author : <Short file description> : <Author name> Copyright (c) : ITER Organization, CS St. Paul-lez-Durance Cedex France This file is a part of the ITER CODAC software. For the terms and conditions of redistribution or use of this software refer to the file ITER-LICENSE.TXT located in the top level directory of the distribution package. The tags $HeadURL$ and $Id$ are Subversion keywords which are filled by the version control system. It is not a Subversion default behavior to fill keywords and it has to be configured on the client side (per file or as a global setting). More information on keyword substitution is available in [RD3]. If the file includes third party intellectual property, the corresponding copyright statement shall be retained or included. The header shall be placed close to the top of the file and enclosed in a comment block appropriate in a given context (e.g., /* */ for Java) Java coding conventions Sun s Java original guidelines shall be followed (see [RD4]). Java packages developed by CODAC shall use the org.iter.codac.<packagename> name prefix. Javadoc annotations shall be used where appropriate to allow automatic generation of source code documentation C coding conventions In the current CODAC context the C language is used mostly to write Linux drivers. The Linux kernel coding guidelines shall be followed for this purpose (see [RD5]) Python coding conventions Python original guidelines shall be followed (see [RD6]) SQL coding conventions SQL is essentially a case-insensitive language, so the following recommendations are mostly to improve readability. SQL keywords shall be written in capital letters (e.g., UPDATE tablename SET ). Table names shall use a so-called CamelCase notation (i.e., no spaces, all words are capitalized; e.g., PlantSystems ). Table fields shall use a lowercamelcase capitalization style (all words but first are capitalized; e.g., attributename ). If a field is designed to be a primary or a foreign key, it shall have a suffix _pk or _fk to emphasize its meaning. It is recommended that table constraints are defined separately from the table definition itself in order to facilitate their removal for debugging purposes. In the case that there is a choice of SQL constructs or data types, it is recommended to use the more portable one XML coding conventions XML documents shall follow the methodology used for the W3C XML Schema definition (see [RD7]). In particular, names of tags and attributes shall follow a so-called lowercamelcase capitalization style (i.e., no spaces, all words but first are capitalized). If the first word starts from a capital letter by its nature (e.g., it is an acronym), the capitalization is retained. Level formatting shall be done with tabs (one tab per level). Page 10 of 28

13 XML namespaces shall be used for reasonably isolated schemas. The format of the CODAC namespace URI is: where SSSSSSSS indicates domain (variable length), and YYYY indicates edition year (e.g., 2010). The domain shall be a word (or a word combination) briefly and clearly identifying a data domain. Mixing of uppercase and lowercase characters is allowed, with words joined by a capital letter without underscores. Examples of the domains are: "PBS", "EPICS", "TTT", "PlantSystem", etc. 2.5 Software Licensing Policy For the sake of the involvement of a wider range of experts, the scientific community and industry in testing and enhancement, the CODAC software may be distributed to organizations or bodies not bound by contractual obligations with the ITER Organization. For this purpose, the distributed software is protected by a special ITER license. The full text of the license is reproduced below: Copyright (c) , ITER Organization Route de Vinon, CS , Saint Paul Lez Durance Cedex, France All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistribution and use are granted solely to the members of the ITER Agreement (the People's Republic of China, the European Atomic Energy Community, the Republic of India, Japan, the Republic of Korea, the Russian Federation, and the United States of America). Organizations, bodies or individuals belonging to the parties other than that in the list above shall seek specific written permission from the ITER Organization before redistribution or use of this software. * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the ITER Organization nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ITER ORGANIZATION BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This text is usually placed in the top level directory of the distribution package under the name of ITER- LICENSE.TXT. Equally, it can be present in the accompanying documentation or in the program s online help. More details on the CODAC licensing policy are available in [RD8]. 2.6 Packaging Guidelines All the software produced by CODAC has to be properly packaged. A formalized packaging step facilitates porting and installation procedures as well as clearly separating the development environment from the production (target) environment. CODAC software uses a native Red Hat Linux packaging mechanism called RPM ([RD9]) Packages classification All packages on a particular Linux system can be classified in the following categories: 1) Packages which are part of a standard Linux distribution (either installed by default or not); 2) Packages which are required by CODAC software but are not a part of a standard Linux distribution (or the existing ones do not have the required functionality); Page 11 of 28

14 3) Packages which are created and maintained by the CODAC team. It is expected that the target system shall have or be able to install packages from the first category. Packages from the categories 2 and 3 will be provided as a part of CODAC distribution. All these packages will have properly identified dependencies, so that installation of the required package automatically brings in all the required support packages Packages naming convention (regular case) Following the established Linux tradition (see [RD9]), the full name of a package shall look like this: <name>-<version>-<release>.<arch>.rpm where: 1) <name> indicates a name of the program (can have hyphens within); 2) <version> is a program version (see section for more information on versions); 3) <release> is a number indicating a version of the package of the same software release. That means that the source code of the software remains the same, but the way it is packaged might be slightly changed. The number starts from 1; 4) <arch> is a target system architecture (x86_64 in our case), or noarch for platform-independent packages. An example of the name would be eclipse-pde x86_64.rpm. This approach implies that only one version of the program can be installed at any given time. Should multiple versions be required or should there be a need to give a common group name and version to a set of packages, the advanced technique may be used, as described in the next section Packages naming convention (advanced case) In the case that a program makes part of a well defined product, its package name may be formed as follows: <prodname>-<prodversion>-<progname>-<prodversion>.v<progversion>-<release>.<arch>.rpm where the <prodname> and <prodversion> are product s name and version in the same format as for the regular program. The rest of the tags are the same as for the regular case. This kind of naming allows several product versions to coexist on the same machine. Of course, apart from naming, packages shall be carefully designed in order to arrive at different places on the disk and to be able to operate independently. The first product version number could be reduced only to major or major.minor number, depending on what level of product maturity is required to be installed. The reason the product version appears twice in the formula above is that RPM is unaware of this useradded complexity and counts everything found between the last two hyphens as a package version. In order for it to be properly compared by RPM taking into account the product s version, both product and program versions have to be present in the notation. The.v serves as a separator for a person to distinguish the two versions. The version numbers for the product and its components are not supposed to coincide and may be different, depending on the development activity of these components. For example, if the product is a CODAC Core System, and the program is EPICS, and minor versions of the CODAC Core System are allowed to coexist on the same system, the package name will look like codac-core-2.0-epics v x86_64.rpm Packages breakdown guidelines Every distributed program has to be mapped to RPM packages during the packaging procedure. Usually it is not a one-to-one mapping. The following recommendations should help to choose the breakdown wisely: If software is packaged by a third party, the package should be retained; Software having a different life cycle (e.g., provided by different vendors) should be packaged in separate packages; Software which is supposed to work on separate machines should be packaged in separate packages; Page 12 of 28

15 Additional functionality of the software, considered as optional in some cases, should be packaged as a separate package; Extensive documentation of a particular product normally comes as a separate package (*-doc.*.rpm); Programs not supposed to be used separately could be joined in a single package. The packages should have proper RPM dependencies where they exist between each other or with system packages. For each product a meta-package may be provided which depends on every package included in the product. Different installation profiles (e.g., PSH or mini-codac) can be handled in the same way. This way, it will be possible to install a whole set of required packages by installing just a meta-package Packaging other than RPM Sometimes there is a need to distribute CODAC software in a non-conventional way. Typical cases include contributions back to the open source community or publishing selected pieces of software for use in projects other than ITER. In this case, there is little sense to distribute binaries, since the target environment might differ substantially from ITER s. Also, there is no need to distribute components which have not been developed by ITER (such as RHEL OS or EPICS); these could be downloaded from their original internet locations. In such a case, a source code has to be provided, accompanied with the relevant documentation; porting has to be done at the software reception side. The packaging would be just a simple source file archive (.tar.bz2 is recommended). As with regular packaging, care should be taken to properly identify versions of the software which goes to such a public release. 2.7 Distribution Guidelines This section describes recommended ways of distribution of the CODAC software. The distribution method depends on the way software is packaged Using an RPM / YUM repository The preferred way of distributing software is to establish and maintain one or several YUM repositories (see [RD10] for more information). This will allow smooth installation and update of the software concerned. Normally, the repository is organized as an add-on to some existing installation (e.g., on top of the regular RHEL YUM repositories), so only CODAC-specific software is placed there. Each repository is described with a small web-downloadable RPM file. Client machines with a clean Linux installation can configure the link to the repository by installing this package: rpm i Note that RPM / YUM repositories contain binaries and rely on specific packaging scheme and dependencies in the original Linux distribution. Consequently, they can only be used with the same distribution for which the software was built and tested. An alternative way of configuring the repository would be manually adding its description into the /etc/yum.conf configuration file or in the /etc/yum.repos.d/ folder (see [RD10]). Once the link has been established, the software can be installed as simple as: yum install <packagename> On the first use you will be asked to import the repository s GPG key (answer yes ). Equally, the same could be done using the graphical wizard which comes with a Linux distribution (pirut in RHEL). Updates are intended to be distributed in the same way. Once they are available, they are published in the YUM repository. On the client side the update of the package to the latest version would simply be: yum update <packagename> Using Red Hat Network Satellite If there is a need to have more control of the software distribution over a multitude of local or remote systems, tools like Red Hat Network Satellite can be used. The Red Hat Network Satellite is based on the Page 13 of 28

16 same concept of YUM repositories, but provides a management layer for them, allowing the management of users and distribution channels, updates to be pushed or for software integrated with the OS itself to be distributed. Target systems installed with the help of Red Hat Network Satellite are preconfigured to use the correct repositories. The client RPM / YUM interface stays the same Using RPMs and self-extracting archives For users who do not have an internet connection, or are not familiar with RPM and want click-and-run installation, an alternative way can be provided, where a product (a set of packages) is bundled to a selfextracting archive which runs a simple script which launches RPM installation. The script could be made graphical if needed (a fancy window with an OK button). This method of installation is commonly used by many commercial vendors of Linux software. The benefit of this approach is that the end result is the same as with installation from the RPM repository, so all the files installed stay under control of system s packet manager and can be tracked, repaired and updated if necessary Using plain tarballs If the software is packaged as a source code (see section 2.6.5), tar archives (tarballs) can be distributed using any file transfer method (such as putting them on a web page or sending by ). There is no control over the software installation or its use in this case Using OS-bundled distribution A less error-prone distribution method (which is quite popular nowadays) is the following. CODAC specific software together with all necessary third party software can be combined with the original OS distribution forming an image of a complete pre-installed OS. The image is written on DVDs (or made available for download) and is then distributed (as an image file download or written on physical disks). The DVD prepared with the help of this image is a live DVD, which allows booting from it on any reasonable hardware and to start immediate use. The data which needs to be persistent (like settings configured by user) can be saved on external media, such as a flash drive. The live DVD can also have an option of transferring the same installation to a computer s hard drive, thus forming an ordinary installation in place. This sort of distribution can be used for quick demonstration, promo actions and as a fast track to actual use of the software. Page 14 of 28

17 3 Software Quality Assurance 3.1 Roles and Responsibilities This section presents the actors and their roles and responsibilities Roles The actors in the development process are: 1. Product manager a supervisor of all activities, responsible for overall product releases; 2. Development manager a person defining development policy and supervising developers; 3. Test & QA manager a person supervising the testing process, especially for nightly-builds. Also responsible for overall QA definition and enforcement; 4. Documentation manager a person defining the documentation strategy and enforcing its QA; 5. System administrator a person installing and maintaining machines in the development environment; 6. Developer a person actively contributing to the source code; 7. Tester (Reviewer) a person reviewing the code and running various tests, either existing or specially prepared ones; 8. Documenter a person writing end user documentation; 9. Packager a person performing packaging of the releases, but not contributing the code except for packaging specific changes; 10. Supporter a person delivering support to end users. The subordinates hierarchy is show below: Product manager Development manager Developer Packager Test & QA manager Tester Documentation manager Documenter System administrator Supporter Responsibility chart Some of the roles may be attributed to the same people. The product manager assigns roles in such a way that the role substitution does not defeat the QA process (e.g., a person must not be assigned to review his or her own code). The procedure of delegation of authority has to be put in place, so that a particular person missing at a given moment does not restrain the whole process. Table 3-1 illustrates mapping of roles to responsibilities. Page 15 of 28

18 Activity Roles assignment Release policy definition (features, milestones) Product Development Test & QA Document System Developer Tester Documenter Packager Supporter manager manager manager manager admin RO Consults Consults RO Consults Consults Feedback Development - RO Consults - - Fulfils Test-specific - Packagingspecific Testing - Consults RO Consults Consults Fulfils Fulfils - Packagingspecific Feedback Feedback Documenting Consults Consults Consults RO Consults Consults Consults Implements Consults Feedback Release freeze Consults RO Consults Consults - - Runs tests Packaging - Consults - Consults - Consults - - RO Feedback User support - Consults - Consults Consults Consults RO QA supervision - Contributes RO Contributes - - Feedback Consults - Feedback Development environment - Consults Consults - RO Feedback Feedback Feedback Feedback Feedback Table 3-1: Responsibility chart ( - responsible, - provides input, - implements) Page 16 of 28

19 3.1.3 Configuration control board A software configuration control board (SCCB) is a panel of people involved in the development process. It is a working instrument to follow up current activities. The issue tracking system is a key tool for SCCB work. Main SCCB activities are: 1. Review current progress with respect to the release schedule; 2. Decide on features and bug fixes to go into particular release; 3. Assign responsible persons and milestones to new issues; 4. Review and decide on overdue items; 5. Decide on new software units and their owners; 6. Discuss any particular difficulties and problems which occurred during development or testing. The SCCB shall be chaired by the product manager. It convenes regularly (usually weekly, depending on development intensity) and also for particular topics, as needed. 3.2 Quality Control Quality control (QC) is an essential part of the software development process. Depending on the nature of the software, the control can be strict or relaxed. Relaxed QC is applied during the early software development phase ( alpha versions), or for various types of experimental development (e.g., prototypes). Production software shall be the subject of strict QC Issue tracking Each bug report or feature request which might lead to a change in the product, however minor, is filed as a separate entity in the issue tracking system. Dependencies between items, if they exist, must be clearly indicated. For each issue at least the following items shall be recorded: 1. Clear description of the problem or feature together with supporting materials (test cases, screen shots, etc); 2. Short description of implementation (if not trivial), or reference to design document(s); 3. Indication of repository branch and all commits (Subversion revision numbers); 4. Names of tests added or modified in the regression test bed; 5. Characteristic differences in outputs of the regression tests; 6. Indication and justification of change which might affect end users (e.g., compatibility break); 7. Justification if the issue is closed without making changes. It is good practice to introduce a release issue for a particular release and make it dependent on all key features or bug fixes in the release. This will ensure that nothing is forgotten and will facilitate preparation of release notes. More information on issue processing in the Bugzilla environment is available in [RD13] and [RD14] QA records A QA plan shall be written and followed by all stakeholders. The QA process will be supported by a number of mandatory documents. They include: 1. Software requirements specification (SRS); 2. Software design description document (S-DDD); 3. Software test plan (STP); 4. Software test report (STR). The documents should be reviewed and updated at each life cycle phase, as appropriate. During testing, the correspondence of the actual software to the declared requirements has to be verified; any discrepancies found must be properly recorded and followed up. 3.3 Version Control Software version control is a cornerstone of the software development and QA process. The CODAC team uses Subversion software to manage different versions of the software it produces. This section summarizes Page 17 of 28

20 the methodology for organizing a repository for CODAC-related development. It is assumed that the reader knows the basics of Subversion and its terminology. Extensive user documentation is available in [RD3] Storage principles The following are some guidelines on what has to be stored in the repository: Source code with associated building environment (scripts); Canonical test outputs; Design support information (models, diagrams, etc); Associated documentation. The list above applies not only to the information being worked on, but also to the deliverables from various contracts and procurements (e.g., selected parts of the PCDH deliverables or R&D contract deliverables). The following things should not normally be stored in the repository: Derived data (that which can be obtained from automated processing, such as compilation, stylesheet transformation, javadoc generation, etc) unless the process of its creation is non-trivial and is difficult to be fully automated; Binary files (especially executable binaries) unless they are an integral part of the software (e.g., picture files, project files, etc); Any sort of run-time, dynamic, operational data; Information which is a routine product of some programs rather than a human creative work (e.g., daily reports, logs, etc). Databases are normally better suited for this; Huge files (usually need special handling); User manuals for CODAC software (these require review process, which shall be done via IDM); These guidelines are neither exhaustive nor imperative. The decision to put a particular file into repository should be based on common sense, experience and best practice. The repository must be operated in a way that traceability of information is maintained. This is supported by several measures: Well chosen top level breakdown, so that changes at that level are rare; Well defined procedures for product life cycle, including obsolescence management; The information shall never be physically deleted from the repository (unless extreme cases, such as a legal claim); Move or rename operations shall be properly logged; The information shall not be excessively redundant or blindly replicated Top level breakdown The URL of the CODAC repository is: Here codac/ refers to organizational breakdown, i.e. to the area managed by the CODAC team. Within it the following top level breakdown is implemented: /iter/ codac/ contracts/ <YYYY>/... design/... dev/ (deliverables of various contracts) (yearly breakdown seems to be most convenient for browsing) (various design works not directly related to the software) (software development area for central CODAC) (software units, see below) units/... obsolete/ (obsolete units are moved here)... i&cdev/ pbs<nn>/ (folder for PS specific developments) dev/ (PS software)... (same organization as for /iter/codac/dev/) Page 18 of 28

21 plcdev/ (PLC-related development (Windows / STEP 7))... (same organization as for /iter/codac/dev/) css/... (same organization as for /iter/codac/) For the i&c/ and contracts/ folders the folder hierarchy will be complemented by a similar one in IDM. The general idea is that document-oriented deliverables (like Microsoft Word or Excel) will be kept in IDM, whilst software-oriented deliverables will be placed in Subversion. In the case that contractors require instant access to Subversion for their own development (e.g., prototyping) they should allocate a subfolder in the contracts/<yyyy> tree. The <YYYY> is a current year. It is suggested that CIS-related software is managed in the same hierarchy /iter/codac/ whilst CSS related software resides in a separate folder /iter/css/. The reason for that is that interlock implementation is likely to share a significant part of code base with CODAC, whereas safety is likely to be implemented completely differently. Clear separation of safety also helps to cope with regulatory safety requirements. The folders in the repository hierarchy shall have short names, all lowercase (unless imposed by some product) and use hyphens as word separators. The length of the folder name shall not exceed 32 characters Software units A suggested development approach is to follow unit testing pattern, where the whole set of software is broken down into rather small pieces and then an aggregation (integration) logic is defined on top of them Definitions In order to define software structure in the repository, common names for software pieces are proposed as follows: Software Module a piece of software possessing a well defined function (functions). Software Subsystem an autonomous program (programs) providing a high-level function or functions. Software System an integrated complex of subsystems delivering complete solution for a given problem. Software Unit a collective name for module, subsystem or system. Modules may exhibit strong dependencies between each other. Typical examples of modules are libraries or drivers. Subsystems normally should have loose coupling between them and communicate through well defined interfaces. Subsystems should be able to continue working if other subsystems manifest malfunctions. Examples of subsystems are the central alarm handler or the central data archiver. Systems shall be able to act completely independently from other systems. Examples of systems are CODAC, CIS, CSS, CODAC Core System. The higher level units (systems or subsystems) normally act as aggregators for lower level units (subsystems or modules). A system may include an arbitrary number of subsystems or modules. A subsystem may include an arbitrary number of modules. This is illustrated in Figure 3-1: System Subsystem Subsystem Subsystem Module Module Module Module Figure 3-1: Functional aggregation of software units Note that this aggregation is purely functional; it does not mean that in the repository a folder of one unit is a subfolder of another unit. In fact, in the repository all units are stored in a flat structure: Page 19 of 28

22 dev/ units/ <unit1> <unit2>... obsolete/ <unit1> <unit2>... The aggregation knowledge is kept in the build logic of units. Equally this means that the pattern of software storage in most cases does not match the product installation pattern. This feature actually gives flexibility, especially when one unit is reused by several others (then there is no question in which hierarchy it should be placed). The drawback is that a flat folder with all units might become difficult to navigate. The basic guidelines of breaking down software into modules are the following: Software having different a life cycle (e.g., coming from different vendors or released at different milestones) has to go into different modules; A module normally should be written using a single programming language; A module should be autonomous enough to allow standalone testing of its functionality; A module should be small enough to be manageable by one active developer; A module s documentation and tests should be part of the same module. Higher level units (systems and subsystems) shall not contain anything other than what is needed for integration (e.g., an integrated build script or common documentation). The rest of the code goes in the corresponding modules and is just referenced in the building environment of the aggregate unit Unit naming convention Each unit shall have a unique name following the convention: t-cc..c[-cc..c]* where t designates the type of the unit (s system, b subsystem, m module). The rest of the string is a short recognizable name of the unit of a variable length of alphanumeric characters cc..c, not less than two characters (not counting the first hyphen). Words in the name shall be separated with hyphens. All letters in the name shall be lowercase. The total length of the name string shall not exceed 32 characters. Examples of names: m-ni-pxi-6259-driver, b-alarm-handler, s-codac-core. The words in the name must not be used to build a hierarchy with the help of word separators. The name is assumed to reflect a function, not a hierarchical breakdown Unit version numbering Each unit shall maintain its own versions independently of any higher level products it might be part of. The version numbering for CODAC-developed units shall be a classical one, X.Y.Z, with a major number X meaning major upgrade (possibly incompatible), minor number Y meaning enhancement (normally staying compatible) and bug fix number Z meaning bug fixes and small improvements. All numbers start from 0 and may exceed 9. The major number for newly developed software is 0; it stays zero until the first stable release. This way, versions serve as a means to track software features and stability. If possible, no special meaning should be associated with versions numbers. Developers should not be bound to maintain specific version numbers because of external conditions (such as public announcement), as it may cause serious inconvenience in the development process. For software being actively developed the alpha (a) and beta (b) qualifiers shall be used (see section for more information what alpha and beta mean). They are inserted between minor and bug fix number (example: 2.0b3). In this case the bug fix number changes its meaning to the number of the corresponding alpha or beta release; these numbers start from 1. Stable versions (marked with X.Y.Z) shall not have alpha or beta qualifiers. The version tags for imported products (not developed by CODAC) shall be those assigned by their vendors. They may differ from the traditional X.Y.Z scheme given that they allow proper lexicographical comparison between releases. In the case that the imported product does not have a clear notion of versions the version shall be assigned by the person doing import. Page 20 of 28

23 Unit internal structure Each module, subsystem or system is assigned a folder in the repository. The organization of main folders is the same for all types of units: <unit-name>/ branches/ (forks for features) <feature1 tag> (same organization as for trunk/ within)... (more features) tags/ (release/milestone tags) <release1 tag> (same organization as for trunk/ within)... (more releases) vendor/ (optional, used for third party software) <release1 tag> (same organization as for trunk/ within)... (more releases) trunk/ (main tree) pom.xml (unit control script) doc/ (unit documentation)... src/ (source code) main/ (main build artifact) <lang> (product language, such as java, c or python)... (source code of any complexity) resources/ (application resources)... config/ (application config files) (other folders, if needed) tests/ (unit tests) <lang> (tests language, such as java, c or python)... resources/ (test resources)... config/ (test config files) (other folders, if needed) The branches / tags / trunk breakdown is a typical arrangement of a product, recommended in the Subversion documentation ([RD3]). The vendor part is optional and used to keep original copies of third party software (other than that, its use is identical to the tags folder). Since the control software for unit builds is Maven, the organization of trunk/ and all similar folders follows Maven conventions ([RD11]). Not all the folders suggested by Maven have to be present. The file structure under main/<lang> or test/<lang> is not defined in this document. Depending on the product nature (EPICS application, Linux driver, etc) it is up to more specific manuals to define the internal layout. The tests/ folder records not only test program codes, but also canonical outputs. Work is ongoing to automate unit creation and for making basic unit consistency checks in the repository Unit control script The top level file pom.xml located in the unit folder is a unit control script. It shall be always present in every unit and serve as an entry point for Maven-driven builds. Typically, at least the following actions ( goals in Maven terminology) have to be defined: compile and test. They launch appropriate tasks for the unit as a whole. Apart from goals, Maven also allows the definition of build the configuration, such as environment variables or project dependencies. It is recommended to use Maven for underlying software build operations as well. However, if this is not practicable (e.g., if the building infrastructure already exists), Maven can delegate underlying builds to some other tools, like make or ant. For the purpose of software QA some general information shall also be defined and stored in the control script. This information includes: 1. unit name; 2. unit summary (one line); 3. unit description (text); Page 21 of 28

24 4. unit version; 5. unit owner and contributors (persons); 6. unit vendor (organization); 7. unit license(s). Some other information could also be defined; Maven provides built-in infrastructure to store this kind of data. This information is then used for administrative and statistical purposes. Use of the unit version may be more advanced than just for developers interest. If there is a need to use a version tag somewhere inside the product (e.g., show it to the end user in the About dialogue), a good practice would be to store the version number in a single place across the unit. A unit control script is an ideal place for that; the building environment can be set up to pass this information into underlying builds. This way, there will be only one place with a version tag to maintain. More information on Maven and its particular use at ITER is available in [RD12] Principal operations on a repository The operations described below are largely compliant with the general Subversion methodology described in [RD3]. This section focuses on points which present further customization or are of particular importance for the CODAC development process Check out and check in Usually there is little sense to check out the entire unit folder, since it contains many branches and / or releases and thus consumes space and brings much duplication. Normally, only the trunk or one of the branches should be checked out. It is recommended that the name of the extracted portion is indicated in the target folder name with some sort of suffix. This suffix stays local and will not affect names in the repository, but will help in local navigation. Example: svn checkout m-plc-sample-trunk When doing commits, it is important to remember that Subversion is a collaborative environment, and someone else might be changing the same code as you, even if you do not expect this. The safe commit procedure consists of three steps: 1. run svn status (and svn diff, if necessary) in order to check that your set of changes is concise and clean, and no accidental or temporary changes have crept in; 2. run svn update to synchronize your copy with the one in the repository. In many cases it will result in no changes, meaning you can safely proceed. If there are changes, you should review them and decide whether the combined change set (yours + repository s) is coherent. If there are conflicts, they must be resolved before doing the commit. By default the repository s copy always takes precedence (unless something was committed by mistake) and so the person trying to do the next commit is in charge of conflict resolution; 3. run svn commit to submit your changes. It is important to keep changes to a practicable minimum and to avoid changes in places which are irrelevant to the current change (such as massive formatting changes) Working with a trunk Trunk is an area for the mainstream development. Most development activities occur in this area. The decision when exactly the activities should be moved from experimental branches to the trunk, or vice versa, is taken by the unit owner; it does not depend on the life cycle of products using this unit. The code checked in the trunk must be stable enough to be compiled and submitted to regular testing (the tests themselves can fail). This is needed to support the overall nightly build procedure occurring on units trunks. If there is a need to commit a really unstable code, a separate branch must be allocated to it (see section ). The unit version string stored in the unit control script of the trunk shall always be a fixed sting TRUNK. This way there will be a clear indication in the built software that this is a running development version. Also, it will eliminate differences in test outputs related to regular changes of unit versions Working with tags Tags are used to indicate milestones in development or to name a particular snapshot of code. Tags can be classified in several groups: Page 22 of 28

25 1. unit s own version tags; 2. version tags of the product embracing this unit; 3. temporary tags. Unit version tags are used to track a units own evolution. In order to distinguish this group, it is proposed that the tag format is v<unitversion>. For example, for the unit that has reached version the tag will be v Version tags of products including this unit are formed as <productprefix><productversion>, where the product prefix is a well defined name for the product. An example would be CODAC-CORE Tags from the first two groups listed above shall stay forever and never be removed from the repository. They serve as reference information and may be used at any given time later on. Temporary tags are created for convenience of development (for instance, to pass a ready piece of code from one development group to another). They can be created at any given time and should be sufficiently descriptive; however, no particular naming convention is imposed on them. As the name implies, these tags will be purged from the repository when they are obsolete or no longer needed. The information about which version of unit goes into this particular product is kept in the unit control script, as explained in section That is, if one wants to know what version of the unit was present in the particular product, he or she should look into.../units/<unitname>/tags/<productname><productversion>/pom.xml for the unit version string stored there. The unit version string shall correctly reflect the unit version for all but temporary tags. The tagging operation creates an identical copy of the source. Normally during a version stamping operation at least the version number has to be updated in the code. This is why it is recommended to do version stamping in two steps: 1. Tag a new version in Subversion (svn copy); 2. In the tagged snapshot, modify the version string in the unit control script to the one required (svn checkout + svn commit). Apart from this version update case, it is generally not recommended to do any development activity on the tags/ or vendor/ folders or even check out these folders. Though Subversion gives no particular meaning to these folders, logically they are very different. Tags, once done, are not supposed to change; thus neither renaming of tags nor change of tagged folders contents is allowed. If there is a need to get contents of a tagged folder on the local disk, the svn export command shall be used rather than the svn checkout Working with branches Branches are used for feature specific development or parallel support of several versions of code. Two main categories of branches are used: 1. Feature branches; 2. Release branches. A feature branch is opened whenever is a need to implement a rather complex feature which will render the source code unusable or unstable for some time. Small fixes can be done directly on trunk or release branches (see below) without forking a separate branch. A release branch is a branch used for release preparation. It accumulates all changes which go into the specific release. It is a responsibility of unit developers to propagate changes from the trunk or feature branches into release branches. In order to decrease double commit effort, this propagation ( merging in terms of Subversion) could be done close to the release preparation stage rather than on each distinct commit. Section describes procedures to handle release branches. Feature branches shall have descriptive names; however, no specific naming convention is defined for them. Release branches shall have names with the format <productprefix><productversion>, where the version is a product version reduced to a major.minor number (maintenance releases do not require parallel support and thus there is no need for a separate branch). Branches are considered as temporary items and will be closed (deleted from a repository) at due time. A feature branch is closed whenever the feature is merged back to the source it was designated for (a trunk or a release branch). A release branch is closed when the support for this release ceases. In this way, only active branches will be listed in the branches/ area. There is no real danger of deleting a branch from the Page 23 of 28

26 repository, as Subversion keeps track of all changes anyway and allows resurrecting deleted branches later on, should this need occur Working with third party software Third party software shall be imported in the vendor/ area with a proper version tag of that software. The files under the vendor/ area will be exact copies as received, no CODAC-specific changes are allowed there. In order to work further with this software it has to be promoted to the trunk area (or one of branches) and modified there as needed. For the purpose of packaging it is recommended that the distinction between the original code and the CODAC-specific code is maintained. Once the source is modified, a patch file can be generated with the help of a diff utility. This patch file (or several, if needed) is placed under version control as well. The RPM builder supports applying patches to the original software during the package build; this feature should be used Version control systems other than Subversion In some cases there is a need to use a version control system which is not an ITER standard. A typical case would be when ITER contributes to development of some third party software, which is then used by the CODAC system. This external software is likely to have its own version control system and its own procedures on top of it and ITER procedures and methods will likely not applicable directly. In such a case the software should be treated as an external product with clearly defined releases or milestones. CODAC developers actively contributing to this software will work directly on a third party repository (exact procedures to be agreed between the CODAC team and product owners). When the feature or the release has to be made available to the CODAC software, it has to be tagged and imported into the corresponding unit in CODAC s Subversion under the vendor branch (see section ). The vendor branch then has to be propagated (patched for CODAC environment if needed, etc) to the trunk or the appropriate branch using the same methods as for any other third party product. If there is a need to introduce changes which go into the product mainstream, they have to be introduced directly in the third party repository. Synchronization between different version control systems is generally not trivial, so it is recommended to keep such resynchronization operations to a minimum, using only well defined milestones. Using this approach, two main objectives are satisfied (at the expense of synchronization work): 1) developers work productively in the native development environment of the third party software, and 2) all software used by CODAC stays under CODAC Subversion tracking mechanism. 3.4 Software Life Cycle CODAC software is not very different from any other software, so it follows classical software life cycle pattern: 1. Development; 2. Testing; 3. Documenting; 4. Release cutting; 5. Porting and packaging; 6. Release; 7. User support. The sections below go into greater details for some of these steps Parallel product versions At any given moment there will be a single principal version ( current release ) defined for each product, which is shipped to end users by default. Apart from it, there could be more versions which are exposed to the end user and thus have to be supported one way or another. From the life cycle point of view, all versions can be classified in the following categories: 1. Alpha -version indicates that software is under development; it serves to mark internal development milestones and is not exposed to end users. No technical support of any kind is Page 24 of 28

27 provided. An Alpha -version is a phase when features requested by users on the previous versions of the product are implemented; 2. Beta -version indicates that the software has major features targeted for the release, but its stability or usability are not yet that of a stable release. Beta -versions can be presented to end users interested to be testers of the newly developed features. This phase enjoys full technical support, receives bug fixes and improvements, but has no commitment on software stability or performance; 3. Stable version a principal software version given to all end users by default. It enjoys full technical support, receives bug fixes and has commitment on stability and performance; 4. Obsolete version a version which is phased out and is no longer supported. It is not given to end users, has no technical support apart from help with migration to a stable version. No bug fixes or development of any sort is done on obsolete versions. From the Subversion point of view, alpha and beta versions live on trunk, while the stable version lives on the release branch (see section for an explanation of release branches) and obsolete versions have no branches allocated at all. This means that in a regular situation at least a trunk and one release branch are opened and can receive commits. In some cases more release branches could be opened (e.g., when beta software is not yet released, but there is a need to start alpha development for an even newer version, a release branch for the alpha -version has to be allocated). It can be observed that even in a regular situation more than one place to commit exists. This may cause confusion among developers ( where shall I commit? ) and, in general, generates some overhead on maintaining parallel developments in sync. This is why the number of parallel open branches has to be kept to a minimum. When deciding where a change should go, the following simple rules have to be applied: 1. if a change is an enhancement, it should go into alpha / beta -versions only, i.e., into the trunk; 2. if a change is a bug fix, it should go into all active versions, i.e., both into the trunk and the release branch. Exceptions to these rules have to be approved and applied in a particular manner Environment setup Setting up a development environment is a prerequisite for development. The servers listed in the section 2.3 are set up by the system administrator. Installation of any additional packages to the regular system setup must be tracked and justified. The list of all packages required for development is to be kept up to date. The system administrator will also manage user accounts and proper access privilege assignment. In order to facilitate maintenance, preference should be given to development of software packages already existing in the OS distribution. Each non-standard package or non-default version of it requires dedicated maintenance and thus their introduction and use must be justified. System upgrades or migrations should be planned in advance and coordinated with the development team Development Depending on the nature of a change, the development occurs either on a trunk or on a release branch (as described in section 3.4.1). The development process should be organized in such a way that most of work occurs on the trunk. Developers working on the same area must coordinate their actions and follow collaboration practices (see section ). In the case where there is too much interference or code incompatibility, separate feature branches have to be allocated. It is not recommended to keep feature branches open for a long time, as the amount of merging work afterwards might be substantial. Once the feature is complete, unit tests are added for it (if possible) aiming to cover as much of the new code as possible. If the developer is not sure whether the fix affects something else, all regression tests existing for this unit must be executed locally and compared against reference output (the one saved before introducing the change). Once the feature passes the tests and it works as expected, the fix is passed to an independent person (usually another developer familiar with the code) for review. Review includes independent compilation and execution of the relevant tests. All actions are recorded in the issue tracking system. Page 25 of 28

28 It is recommended that unit owners explicitly stamp stable unit versions by tagging them as described in section This will help in during the release preparation and is a good practice in general. For transparency of the development process the following automated daily reports (sent by to designated mail list) should be provided: 1. The list of all commits to the entire CODAC source tree, grouped by units and Bugzilla identifiers. 2. The results of the nightly builds (success / errors). These have to be reviewed systematically and followed up Testing The testing procedure has to be automated as much as possible. The regression testing procedure has to be organized so that each test produces an output which is thoroughly reviewed once and stamped as canonical by saving it in the corresponding area in Subversion. During the subsequent development only differences in the test outputs ( diffs ) have to be reviewed. The regression tests are executed automatically on daily basis. The test scripts should be able to read the units test directories and to extract a list of tests to execute. If the unit was not rebuilt during the last day and tests were not modified, no re-execution of tests will take place. The developer committing code to the trunk monitors the changes in the test output the day after the change. Diffs are assembled to a report and sent to a dedicated mail list available to the development team. The diffs must be reviewed by the committing developer, approved and updated in the output repository (promoted to canonical). There will be a possibility for a developer to run a selected set of tests as if they were run overnight and check their outputs. The test & QA manager oversees ongoing activities in the regression test bed and makes sure that there are no unresolved diffs. Some tests require a specific setup (e.g., hardware connection). As far as is practicable, dedicated hardware with exclusive 24/7 access should be allocated for these tests Documenting The documentation process shall be parallel to development. The documenter monitors available sources, such as resolved issues in Bugzilla and is proactive when a new important feature or bug fix is implemented. He or she should prepare a comprehensive description of the nature of the change for the end user. Developers contribute to the description if needed. This activity allows the product documentation to be improved in the course of product development, thus spending less time on documenting during the product freeze. Finalization of documentation occurs during the release freeze. Samples and templates for the products have to be prepared by developers and documenters as needed. The purpose of samples is to illustrate important out-of-the-box features of the product to the end user and to provide skeletons for his or her own custom applications. Some guidelines on documentation preparation are given in the section Release cutting Release cutting is a procedure of code freeze and execution of the release tests Code freeze The date of code freeze is announced in advance. Before the code freeze the development manager creates release branches for all units which are supposed to go into the product. Release branches are created from the previous product release tag, or from the latest stable unit version in the case where there was no previous product release tag. In the case of a maintenance release, a previous release branch is used directly. Once the release branch is established, it is a unit owner s responsibility to upgrade this branch to the unit version which is supposed to go into the product release. Normally this is done by merging the last stable version of unit into the release branch. In the case where there was no development since the last product release, no work is required. By the time of the code freeze, the test & QA manager takes a snapshot of all the release branches. These codes are submitted to internal testing. Page 26 of 28

29 Release tests Release tests include: 1. regular nightly build and testing; 2. advanced tests, as described below; 3. installation of the target test system; 4. execution of tests on the test system following the product test plan. Advanced tests may include: code coverage tests (using a regression test bed or part of it as a basis); stress tests for extreme loads on certain important characteristics such as performance; compatibility tests between last and previous versions of products using interface points which were not supposed to change throughout the given release; memory operation validity tests. Compatibility tests should be run on the following levels, depending on the intended usage of the product: software compatibility (e.g., recompilation with new headers/libraries works); binary compatibility (e.g., dropping in a new shared library instead of the old one works); protocol compatibility (e.g., the changed system does not break existing communication). Product tests are performed by designated testers. Test reports have to be prepared to record the results of the tests. If a code change is needed, it will be introduced in the release branch by the developer of the corresponding unit. After the release is finalized, the fix should be propagated back to a regular development area (e.g., into the trunk) in order to be present in future releases. Once the tests are found to be satisfactory, all the release branches are tagged with a release tag, and these tagged sources are packaged as a final release (see the next section). Special attention should be paid to ensure that only release-tagged source files go into the release. A stable release must satisfy the following criteria: there should not be a compatibility break (unless expected / recognized / documented); code coverage should be maintained close to 100%; stress tests should manifest no significant performance degradation in comparison with previous releases (unless expected); there should be no major faults (like memory violations) leading to application abort; documentation should be up-to-date and describe a migration path from the previous version Porting and packaging The porting step is not relevant in the CODAC environment at the moment, since only a single platform (RHEL x86_64) is used. However, even for the single platform, the production environment might be different from the development one (e.g., a different set of packages installed), so this step is important. In future, there will likely be a need to support several versions of the same platform or to port selected software components to some other platforms (such as Windows). Prepared and tested sources are passed to a packager. The packager produces three sets of RPM packages out of them: 1. production packages (*.rpm) 2. source packages (*.src.rpm) 3. debug packages (*-debuginfo.rpm). Additional bundling may be performed on top of these packages, as described in section 2.6. Should the need occur to fix source codes during this phase, the changes have to be contributed back to the main source tree Release The released software is published using one or several of the distribution methods described in section 2.7. Source and debug packages should not normally be a part of a distribution but could be made available for download on demand. Page 27 of 28

30 New releases have to be announced to end users, especially to those waiting for particular features or bug fixes User support A support desk has to be established and manned during the entire support period. User feedback will be collected by the support desk via a dedicated list. Each support request has to be recorded in the issue tracking system, investigated and responded to. The first response should come within one working day and will contain a resolution, a request for more information, or an indication of when the resolution will be provided. Issues requiring changes in the product have to be brought to the SCCB attention and their inclusion in future releases has to be decided. Summary support reports have to be compiled periodically and submitted to QA personnel for analysis. 3.5 Documentation Guidelines Software documentation is an important component of a software QA program. It can be split into two categories: 1. User documentation; 2. Internal documentation. Both shall be done to a reasonably high level of quality. User documentation requires peer review for every public release. Efforts should be made to keep the documentation clean, concise, consistent and up-to-date. Documentation handling depends on its source. Some typical examples are explained below Documents prepared by developers Documents written by developers will normally be put in IDM. This will facilitate document versioning and identification, as well as enabling traceable review process. IDM will be the master source of these documents, and they will not be placed under Subversion control. The environment for building should be set up to receive these documents from IDM and include them in the packaging. For document preparation it is recommended to use a common template, such as [RD15]. The format for distribution is PDF Generated documentation Many tools exists to derive documentation from the software (source code, models, etc) itself. Very often this process can be automated and executed as many times as needed. Such documentation shall be versioned and maintained in sync with the package of its origin. Since it is derived information, this documentation will not be stored in Subversion. It is rather the generator scripts which should be placed under version control Third party documentation The documentation coming with the third party software may be used internally or redistributed together with CODAC products. In the latter case, it will be part of the unit keeping the corresponding software, and thus has to be managed via Subversion. Like the source code, is will be stored in the vendor area of the unit (see section ). The Unit owner is responsible for maintaining this documentation. Page 28 of 28