CASA Naming Convention Requirements

Status

RJS - 5/20/14:
  • Revising based on questions raised by Juergen and subsequent feedback from Lindsey.
  • Added Pipeline field (7.1) as well as plain English change log for release packages (4.4). Also revised derived requirements for unique ID progression (4.2).

RJS - 4/30/14:
  • Incorporated feedback from B&T team.
  • Need to review with CSSC.

RJS - 4/25/14:
  • First draft of table based on e-mail exchanges between Scott, Darrell, Mark, Steve, etc.
  • Soliciting requirements from team.

Introduction

This page aims to capture the requirements for an updated CASA Version Identification and Naming Convention. The reporting of the content changes (fixes and features) within a package version is deeply inter-related, and is therefore also within the scope of this page. Requirements are being sought from a number of stakeholders, with a focus on the CASA team and CSSC.

Please note that there are many possible naming conventions and that is not the focus of this page. The intent is to document the actual requirements of a suitable approach for CASA. Design and implementation, to the approved requirements, will be the responsibility of the CASA Build & Test team. The proposed implementation will not be judged on whether it is the ‘best’ implementation, but rather on its ability to satisfy these requirements.

Requirements Flow-down

The implementation of the naming convention and content reporting will have flow-down requirements to the following systems:
  • build system (CMake),
  • integration (buildToolWrappers, or replacements),
  • test automation,
  • CASA packaging,
  • CASA publishing and delivery, and
  • CASA deployment.
The flow-down of requirements to these other systems will be considered independently.

Format

Requirements are captured as a matrix in an effort to show both traceability, relative importance of requirements, and compliance status of the proposed implementation (once fully populated).

Requirements

Req. ID High-Level Requirement Importance Derived Requirement Implementation Notes Compliance Status
1.0 General Requirements        
1.1 Each build must have a unique identifier. HI      
1.2 A succinct identifier that can be used in communication between team members, testers and other stakeholders is highly desirable. However, there is no limit on verbosity in the naming convention. HI      
1.3 CASA package names must identify the version of CASA contained in the package, identified by a CASA development cycle. HI   This does not require package names to include Subversion revision numbers. This is becoming increasingly meaningless as CASA is now distributed between three Subversion repositories (asap, casa-data, and everything else), and casacore will be split out to another repository.  
1.4 The naming scheme should reflect the progression of the code from development to release. (e.g., test, stable, prerelease, release) HI      
1.5 The naming convention must distinguish between packages containing the same source code and tested to the same level, but rebuilt to fix packaging issues. HI      
1.6 CASA package names must identify where the package was built, including the OS the package was built on, and the CPU architecture the package was built for. MED      
1.7 The CASA terminal, logger GUI, and download file name shall report a consistent package name. HI      
2.0 User-facing Requirements        
2.1 The package name must be unambiguous, allowing the user to determine which version of CASA they are installing and its relative stability (a test package vs. an official release) without a priori knowledge of the naming convention, or reading release notes. It should also be obvious if it is a precursor to a release or a post-release patch. V.HI      
2.2 There is no requirement for the naming convention to be based on, or consistent with the current package naming convention. However, the version identification should either be consistent with the current convention or sufficiently different to be readily identifiable as a new scheme to avoid user confusion. MED      
2.3 It is desirable to note a lack of backward compatibility with the use of major version numbers, consistent with current CASA custom. LO      
3.0 Infrastructure Interfacing Requirements        
3.1 CASA version identifiers must allow mapping from the version identifier to the exact source code used to build the package. V.HI   Note: CASA is built from several Subversion repositories. These have different change histories. Currently, CASA source must be identified by the Subversion repository, branch, and revision. Including this information in the package name is not required, so long as a unique ID can be mapped to these parameters.  
    MED The version identification system should allow for reporting on the SVN revision number and branch name used for the build.    
    MED Which specific revisions are present in the code base for the build should also be discernible.    
3.2 CASA version identifiers must allow the production of valid package names for all Linux distributions and OS X versions CASA is required to support. HI   Different package managers have different conventions for punctuation in package names.  
4.0 Change log        
4.1 The version identifier scheme must allow for a simple automated system to report, via a change log, which JIRA tickets are addressed by a package. Changes should be reported in terms of JIRA tickets because these are the medium of conversation between developers, management, and users. HI   It would be good if the changelog format could be parsed by a machine reasonably easily, eventually automating the process of posting comments to JIRA tickets that a given test item is ready for user testing (i.e. "ARTT").  
4.2 It should be unambiguous which subsequent packages contain the fixes to previously solved JIRA tickets (e.g. CAS-XXXX is fixed in version A.B.C or higher). HI   This may require embedding Subversion repository, branch, and revision data in build and package identifiers.  
      The version identification number and naming convention must be consistent with the source code configuration control system so that branch management and revision numbers have clear mapping.    
      This will likely require that, in the progression towards a release, the unique identifier count up.    
4.3 Any change log generating scripts should be capable of pulling information from both SVN logs and JIRA. MED      
4.4 It is desirable that the change log for a public release include a 'Plan English' description of major functionality and fixes prior to elaborating any details by JIRA ticket. MED   'Plain English' descriptions would not be necessary for pre-release, test, or stables, given the expected user base of these packages.  
5.0 Packaging & File Structure        
5.1 When unpacked, CASA must reside in a directory that matches the package name. Conventions for a given distribution (such as installing in /usr under Linux) take precedence over this requirement. MED      
      OS X dmg and Linux tar packages that may be installed anywhere in the file system must follow this convention.    
      dpkgs, rpms, and other packages that install in /opt/ must follow this convention.    
      dpkgs, rpms, and other packages that install in /usr/ should follow conventions for that Linux distribution.    
6.0 Maintainability & Design Life        
6.1 It is a goal that the proposed approach be sufficiently robust to be adopted on a 10 year time scale, accommodating anticipated changes in interfacing systems such as revision control system, test automation, etc. LOW      
7.0 Pipeline Integration        
7.1 A field shall be present in the naming convention to indicate the presence (or absence) of the pipeline code as part of the build. HI      

-- RobSelina - 2014-04-24
Topic revision: r9 - 2014-05-27, RobSelina
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback