Getting Started Guide

Overview

Once you’ve completed the physical installation of Sablime according to the Installation Guide, you need to do a couple more things to prepare to use Sablime:

  1. Create and configure one or more Products and Generics.
  2. Create user records.

If you’re eager to proceed, you can use the Quick Start process to get a basic working setup, and then customize it later (if necessary):

Quick Start

$ cd SABHOME # where SABHOME is the location where the binaries were installed
$ ksh ./initsab p=PROD g=GEN prompt=n 
$ . ./set_sablime GEN

The above will create a Sablime product PROD with a generic GEN (where PROD and GEN are names of your choosing), using defaults for all the configurable settings. As part of the setup, it will also create a basic user record for you (using your current login ID). The databases will be in SABHOME/databases. The directory structure for GEN will contain “.”.

The third line sets your working environment to the newly created generic GEN.

Assuming you intend to use the web interface, the final step is to follow the instructions in the Web Sablime Installation and Upgrade Guide.

On the other hand, you can follow this guide to get a fuller understanding of Sablime, and then use the interactive initialization to establish your configuration.

Sablime Basics and Terminology

If you don’t need background on Sablime, you can skip ahead to Creating your Initial Sablime Product and Generic.

Sablime is a Configuration Management system.

Managers, developers, testers, integrators, and other project personnel use Sablime to manage changes to products under development or in maintenance. Sablime keeps data about project files and about any proposed and actual changes to the files.

Sablime Objects

These are the objects managed by Sablime:

File

Project files managed by Sablime are often called source files, and are said to be under source control.

Any file needed to produce, install, or use the software is a candidate for source control.

Files change as project work progresses. It is normal for different versions of a file to be in use at the same time, and not uncommon for different changes to a file to be under way at the same time.

Sablime tracks and labels the changes made to the files under its control. Users obtain versions of files by specifying which changes to include.

Modification Request (MR)

The MR tracks a requested change, such as a feature or a reported bug, from its inception through its eventual resolution, together with any file changes made to implement the request.

MRs progress through a defined life cycle. Each stage of the life cycle has an associated MR state, which determines what may be done with the MR and who may do it. When an MR changes state, relevant stakeholders are notified by email.

An MR in the assigned state can be used (by the assignee) to make changes to files. No changes can be made to a file except with an assigned MR.

Developers, integrators, and testers determine what to work on based on MR states and assignments. Managers track the status of a release by tracking the status of the MRs implementing the changes planned for that release.

Product

The product is the broadest organizational unit in Sablime. Often a product corresponds to a software application, though in some cases an application may be assembled from different Sablime products. Each file under Sablime source control, and each MR, is associated with one and only one product. Products are independent of each other. Customizations done in one product have no effect on other products.

Generic

Within each product are one or more generics. Most often a generic represents a complete development cycle (release) of the product, from requirements through delivery and maintenance.

Although an MR may be implemented in multiple generics, each individual change done with an MR is associated with a particular generic. The files that are part of the product may be used in some generics and not in others.

Directory

Each generic has its own directory tree. The structure of the directory tree, and the names of the directories, can vary from generic to generic. Each file in the generic resides in a particular directory. The directory tree and the locations of files within it can be changed. Unlike files, however, directories are not versioned: Sablime does not track directory structure or file locations for a generic as these change.

Node

A node is an instance of the generic’s directory tree where Sablime places files requested by the user.

The structure of the node matches the directory structure of some generic, and normally the files in the node are all obtained from that generic. A node may belong to an individual user, typically somewhere under the user’s home directory.

Most projects also define one or more reference nodes, in publicly accessible locations, which contain particular versions of the software. For instance, a project that does nightly integration builds for a generic would normally use the same node each night.

Nodes can be unmanaged, meaning that Sablime will create the directory structure, and Sablime commands can place files onto the node, but Sablime doesn’t remember or track the contents or status of the node. Managed nodes, on the other hand, are those where Sablime remembers the parameters used to populate the node with files, and tracks the contents and status of the node.

Sablime includes commands to create, populate, validate and update nodes.

MR Progression

MRs are created to document a flaw or a proposed change to your project and/or its files. Some analysis is often done on the created MR to determine whether to make the change and if so, in which generic(s) to do so.

This table shows an MR progression path. This is a sample process, you may choose to have fewer states, and the events that trigger your state changes don’t have to be as described. These are the default state names as well, and you can rename the states between submitted and approved if you like, to better match your process:

Event MR State
Project Manager/Developer/Customer Engineer creates an MR created
Analysis determines that the MR should be incorporated in this release accepted
The MR is assigned to a particular developer for implementation assigned
Developer submits the MR — Changes are ready for testing submitted
Build process incorporates the MR preitpassed
Integration Test process completes itpassed
System Test coordinator accepts the MR for Testing prestpassed
System Tester passes the MR stpassed
MRs are packaged for delivery and are ready for acceptance test preapproved
Delivery and Acceptance test completed approved

An Example of How to use Sablime

Sablime can be broadly customized. Depending on your project’s needs, you may want to implement a highly controlled process with precise control of which users can perform which operations, or you may want to set up a loosely controlled process where anybody can do anything. You may choose to have as many as five testing states between submitted and approved, or none at all.

For example, the simplest practical process has developers using fcreate to create MRs (creating MRs directly into the assigned state); then using the MRs to change code before they use submit to indicate completion. Someone (possibly that same developer) uses approve when the MR's change is deemed final.

To help you in your consideration of your choices, the following shows a more typical process that includes some early analysis of incoming MRs (to filter out nonsense, duplicate, or impractical MRs), and some levels of integration and system testing of the completed efforts. It is, in fact, the process that the Sablime development team itself uses.

The image shows a parallel progression of MRs in the current and next releases though MR states from created to approved.

MRs are created by the Project Manager in response to customer input, or by developers in response to discovered flaws or for development of new features.

Created MRs are reviewed by the MR Review Board. The MRRB decides if the MR is indeed appropriate for development, and if so, into which development generic it should be accepted. If not, the MR will be killed.

We often develop in two generics at once, one for updates to the current release and the other for the next major release. An MR may get accepted into one or both generics, depending on the MR. The MRRB also decides to whom the MR should be assigned (in each generic) for development.

The developer implements the change, builds and unit tests the change in their own area, and when satisfied with the results, submits the MR.

The nightly build updates a source node with the changes from any newly submitted MRs, and starts a build. If the build completes successfully, and passes some automated testing, it testpasses the MRs to preitpassed.

The Integration Coordinator testpasses MRs to prestpassed to indicate that they are ready for system testing, either individually, or in related groups of MRs.

The MR tester, when satisfied that the MR was properly implemented, testpasses the MR to stpassed. There will also be system wide testing, and regression testing or even beta testing.

Once the release has been placed on the web site, the release coordinator approves the MRs to indicate that they are beyond recall.

The image shows an MR going from created to assigned with detours to mra_study and to understudy states.

When a complex MR comes along, one where we need some technical analysis in order to determine how to address it, we make use of one or sometimes both of the optional study states.

If it isn’t clear whether the issue is valid, the MR will be assigned to a developer for mra_study. The developer will study the request, to determine if it is reasonably doable, and then propose to return the MR to created (with the proposal appended).

The proposal might recommend killing the MR. Assuming, instead, that development is recommended, the MR will then be accepted into a generic.

At this point, it may be decided that a more detailed implementation plan is warranted. In such a case the MR is again assigned to a developer for study within the generic. The MR acquires the understudy state.

The developer studies the MR, and once again, uses the propose command to return the MR to accepted, with the proposal now appended.

Finally, assuming that the implementation proposal is acceptable to the MRRB, the MR is assigned to a developer for actual implementation. The remainder of the process is the same as in the previous illustration.

The image shows a file being gotten, edited and put, using an assigned MR.

Then, of course, there is the part of the development process where files actually get changed. This only happens while an MR is assigned to a developer within a generic, that is, between the assigned and the submitted states from the earlier diagram.

The developer uses edget to check out a current copy of the file from Sablime. The developer modifies the file and then uses edput to check in the file.

He or she can repeat this process for that same file or for an unlimited number of other files. At some point, when the developer is satisfied that the changes for the MR have been completed, he/she submits the MR.

If the testing process discovers a flaw in the implementation of the MR, the tester would reject the MR, returning it to assigned. At this point the developer makes further file changes and again submits the MR.

This basic process can be used to support various overall development approaches, such as incremental or agile, since the Sablime process does not define the scope of an MR. An MR can represent a complete feature, for example, or it can be one incremental advancement to a feature’s development.

Creating your Initial Sablime Product and Generic

After you install Sablime (and a license file) as described in the Installation Guide, you have a fully functional Sablime system. Now you need to establish your first product and generic, and establish their initial configuration.

The initsab command does this. (If you skipped the part about Sablime Basics earlier, and you aren’t familiar with products and generics, you may want to go back).

Position yourself in the directory where the Sablime commands are installed on the Sablime host, and enter ./initsab or ksh ./initsab.

Initsab will ask for information on many of the configurable aspects of Sablime products and generics. Don’t worry about being absolutely correct on these. Except for the location of the databases and the location of the commands, these can all be changed later. In fact, you can use the Quick Start variation of initsab to avoid specifying any of the configurable parameters, and save the details of product configuration for later.

See Managing the Process in the Usage Guide, for details on product and generic configurations.

See Creating a New Product for a description of using initsab.

Among other things, initsab will ask for the Sablime IDs (PTS, or Personnel Tracking System IDs) for users that are to take on certain roles. Please see Sablime Role Based Permissions and Groups in the Usage Guide for information on the purpose and authority of the roles.

Setting up Sablime PTS IDs

Your license says how many users can access Sablime, and now you need to create the Sablime PTS IDs that specify which users can access Sablime.

Initsab will have created the basic PTS IDs of any users you supplied for the role groups. You use pts to add other users and to fill in details for the automatically added users.

The Initialization Script

When users access Sablime on the host (using the Console Interface), they must establish the proper execution environment using Sablime’s initialization script. When users access Sablime through their Web Browser, the initialization is done automatically.

Instruct your users to issue the command . set_sablime GEN (where GEN is the generic they wish to establish as their default) to set up their environment before attempting to use Sablime commands on the host. This can be put into their .profile file so that it executes automatically upon login, if desired.

Your Sablime host environment is now completely established. Web Sablime installation and setup is described in the Web Sablime Installation and Upgrade Guide.


Sablime is a registered trademark of Alcatel-Lucent Inc.
Contents copyright © 2010-2015 Alcatel-Lucent. Permission to photocopy in support of a licensed installation of Sablime is hereby granted.