XILINX - WWIT Design for a Revision and Release Control System Employ Existing RCS records

Doc: Version: Date:

80331535.docx 00.1 December 1, 2011

Revision History:
Name Gerry Glaser Responsibility/Comments First Draft Proposal Date Nov 30 2011 Version 0.1

Introduction:
This document outlines a design for a simple procedure that utilizes existing RCS libraries and commands; and impresses a different level of control on them. The intention is to show the life cycle of files and to also designate and record their intended use. Particular features are the use of a RELEASE mechanism in conjunction with a REVISION mechanism. The design takes special care to directly support the practices that Xilinx follows that correlate quality level with REALM. As well, it makes less casual the creation and maintenance of Libraries without relying upon symbolic links, current working directory, and other artificial mechanisms for depositing and retrieving materials successfully.

Outline of what youre going to read

1. 2. 3. 4. Definitions Summary Command Structure Outstanding Questions

Xilinx Confidential Page 1 of 6

Click here for help on documenting and designing messages

XILINX - WWIT Design for a Revision and Release Control System Employ Existing RCS records

Doc: Version: Date:

80331535.docx 00.1 December 1, 2011

Definitions:
These definitions provide a good deal of the background to the process expressed by these commands. Closely read this Definition section so that you have a deeper understand of what the Commands documented below intend to accomplish. TERM or Abbreviation REPO Short description Repository Explanation of term and how it is used. Each RCS directory structure comprises a REPO. In many of the commands the REPO is required. Rather than supplying the precise directory path to the REPO, simply the handle of the REPO is used. The precise library path is maintained in the REPO LIBRARY. A MARK can be associated with any one revision of a file in a REPO. MARKs can be used to identify a special purpose or a most recent disposition for a given revision of a file. Many instances of each application or system will exist. These are often integrated with other applications within the same realm in order to simulate how the real production applications might behave. Realms use many names and pseudonyms. The specific names are not of concern to this design, but that they are distinct is important. Examples: prod, silver/uat, bronze/dev, copper, tin, crp crp2 When a version of a file is checked out into a formal ENVIRONMENT, a MARK is associated with the revision. These designation must begin with an Alphabetic character. REVISION Arbitrary/seq uential version Controlled MARK Whenever a file is submitted to an RCS repository, a revision is associated with that submission. The revision designations can express multiple branches of development. However, at Xilinx, customarily only a single branch of sequential revisions is used. Normally when substantial functional changes are made to systems and applications, they are tested together in a full release. The RELEASE is made up of each system and the code and data files of those systems where each file is identified by a specific REVISION. Only one REVISION of a file at any given time may be tagged with any specific RELEASE identifier. The sum of all these revisions of files is a RELEASE A RELEASE Library is maintained by Release Management with the qualified RELEASE values that can be used. Each is flagged with a state of ACTIVE or INACTIVE. REPO LIBRARY Dictionary of RCS repositories Activity log A data structure is maintained that records all of the REPOs that have been defined, the ownership for the repository, and the physical location in which it is stored. Whenever a file is submitted to a REPO or retrieved or installed from a REPO, a record is maintained in a log associated with that REPO. This provides the full history of the exchanges between the REPO and the outside world. NOTE: Only RETRIEVEs with a lock are recorded. RETRIEVE Check out When a developer of diagnostician wants a copy of a file from a REPO, they RETRIEVE it. If they lock the file then a record is maintained of when they retrieved and where it was deposited during the retrieve operation. An INSTALL is a formal operation on an in a REPO. For Production and all controlled Click here for help on documenting and designing messages

MARK

Revision Brand Quality level, integration suite

REALM or ENVIRONMENT

RELEASE

REPO LOG

INSTALL

Check out to

Xilinx Confidential Page 2 of 6

XILINX - WWIT Design for a Revision and Release Control System Employ Existing RCS records an environment

Doc: Version: Date:

80331535.docx 00.1 December 1, 2011

environments, only Release Management will use the INSTALL function. A record is kept for each install identifying the target directory and associating a name with the revision of the file in the RCS Library to flag that it is currently installed in that environment. Whenever a change has been made to an existing revision controlled file, or a new file is placed under revision control, it is submitted to a REPO. During the submission process, the intended use of the revision can be identified. Most often this is done by associating it with an ACTIVE RELEASE identifier.

SUBMIT

Check in a new revision

ARCHIVE

Set aside directories

Below each REPO structure (RCS directory) is an ARCHIVE directory. For files that are no longer under control or part of the compute environment, they are moved to the ARCHIVE so that they can no longer be accessed via the RM commands.

Summary:
There are many different revision control systems in use at Xilinx. An unfortunate side-effect of having a Purchase first prejudice is that with each new application or system, there is a possibility that a different revision control system may be introduced to Xilinx. However, resulting from historic practices, predominant among the revision control systems in use at Xilinx is RCS. This document identifies a command structure to overlay and control the use and commands of RCS. It depends strongly on some of the built-in features of RCS that allow a record of the disposition of materials to also be made. As well, it makes use of these features in such a way that a transaction discipline can also be infused in the use of revision control materials. For instance, it is intended that the command structure documented below will allow Release Management to check out all target material for a Release in a single operation without reference to external documentation systems. As such, the below commands attempt to develop sets of materials/files. Those sets are constructed using the MARK feature of RCS.

Though it is possible to refine this design using other RCS features (such as branches, merges, etc.), none of those were incorporated explicitly in creation of this design. However, enough research was completed to insure that were these techniques to also be utilized in the future, that the fundamental design here would be compatible with their use. In some future manifestation of Revision Control, different tools (with comparable capabilities will be utilized; for instance Subversion)

Command Structure:
Notation: <name> [] | RM DEFINE - a variable value - optional and not required value. Either a default is used or behavior differs if this value is not included - optional (or) values. One of several values is required. The value can be repeated <directory> <REPO> [<description>]

Repositories (REPO) in RCS are storied in directories. This function is used to create and/or record where a named REPO is stored associating a specific directory with the REPO name. Though not common, multiple REPO names may be associated with a single directory. The record of REPO to directory assignments is stored in the REPO LIBRARY that documents all REPOs. RM ASSOCIATE <directory> <REPO> ENVIRONMENT

This function is used to identify the directory that is populated by this REPO for a given ENVIRONMENT.

Xilinx Confidential Page 3 of 6

Click here for help on documenting and designing messages

XILINX - WWIT Design for a Revision and Release Control System Employ Existing RCS records

Doc: Version: Date:

80331535.docx 00.1 December 1, 2011

This association is used with the INSTALL function in order to reduce errors and to identify how REPOs are formally used in the release management process. NOTE: Implemented using links from the REPO to the Environment that are stored within the RCS structure (symbolic). RM SUBMIT [<dir>:]<filename> <REPO> [<RELEASE>[:<REVISION|MARK>]]...

A piece of development has been completed. This function allows the developer to insert the revised file into the repository directory associated with the REPO. If the submission is intended to be used as part of a future RELEASE that can be identified on this command. If a previously submitted revision is to be tagged for a future RELEASE then the REVISION or NAME of the version can be specified. Where: filename RELEASE the directory and filename to submit. If no directory is designated then the current working directory is assumed. This identifies the MARK to be associated with this submission. If the optional Revision or Mark is specified then the function assumes that a new version is not being submitted, but that rather only that a REVISION or other MARK are to be associated with an already libraried version. This parameter may be repeated if multiple MARKs are to be associated. <REPO> [<RELEASE|REVISION>] [<target_directory>] [<flags>]

RM

RETRIEVE <filename> Where:

Get a copy of a version of a file that is in the REPO.

filename name of file in repository (no directory designation) RELEASE|REVISION either the version specified by release MARK or Revision may be specified. If this value is not specified, then this defaults to the newest version. target_directory location in which the file is to be deposited. If this is not supplied, then the current working directory is assumed. If the value - is provided, instead of a real directory, then the lock operation is completed, but no the physical retrieval is not completed. flags -lock[:<days>] lock this file version so others know you intend to revise it. Optionally, you may identify how long to hold the lock. After that number of days, a different user is allowed to issue the UNLOCK command on this file. RM UNLOCK <filename> <REPO> [<RELEASE|REVISION>]

Unlock a file that was previous locked. This command is only issued when a developer has decided to abandon development work they have completed. This same command can be issued by a different user if a previous lock has EXPIRED (see RM RETRIEVE flags) RM INSTALL <filename> <REPO> <RELEASE|REVISION> <ENVIRONMENT> [<target_directory>]

This command install file into a controlled ENVIRONMENT. A MARK is placed to identify the revision which has been installed in a specific ENVIRONMENT. A given revision may actually be MARKed as installed in multiple ENVIRONMENTS. Where: target_directory RM this is only specified as an override. Normally a registered Environment will already identify the target directory.

COMPARE [<dir>]<filename> <REPO> <RELEASE|REVISION> [<RELEASE|REVISION>] This command compares versions of the same file.

Xilinx Confidential Page 4 of 6

Click here for help on documenting and designing messages

XILINX - WWIT Design for a Revision and Release Control System Employ Existing RCS records Where: filename

Doc: Version: Date:

80331535.docx 00.1 December 1, 2011

the directory and filename to compare. If no directory is designated and the comparison is not between two REPO versions, then the current working directory is assumed. RELEASE|REVISION If the second set is specified, then this is a comparison between two version stored currently in the REPO <REPO> [<version>]

RM

ARCHIVE <filename>

This command is used to remove a file from revision control. This is done when the file is no longer part of the compute environment. This does not remove the file from any directory in which it was released. It simple retires it from further development or access from the RM command structure. Where: Version This can be any of RELEASE, REVISION. If specified, then rather than the archive operation, the specific version of the file si removed from the archive. This functionality is only used when a SUBMIT has been done by mistake.

Xilinx Confidential Page 5 of 6

Click here for help on documenting and designing messages

XILINX - WWIT Design for a Revision and Release Control System Employ Existing RCS records RM REPORT <filename> <REPO> [<version>]

Doc: Version: Date:

80331535.docx 00.1 December 1, 2011

This command is used to report the history of a file through Revision Control. Where: Version This can be any of RELEASE, REVISION, or ENVIRONMENT. If specified, then the report produced does not report the entire history, but rather only exposes information about version specified.

RN HELP List the above command and help on the parameters

Outstanding Questions:
Should switches be used to make command more flexible that positional syntax

Possibly both positional and switches might be considered (ala axis_env)

Should there be a default target directory associated with each ENVIRONMENT for each REPO? (This could actually be record using a symbolic link in the RCS directory.)

Do we need environments by site in order to handle materials that must be released to multiple sites?

Xilinx Confidential Page 6 of 6

Click here for help on documenting and designing messages