SCM Design Patterns: Paper Forms

[article]
Part 1

Configuration Management (CM) can be viewed from many perspectives. In the day-to-day world, we see many  examples that inherently have CM in the makeup of their form and function. Take for instance, the example of a modern car. It has thousands of parts that comprise the complete vehicle, and the builders of that car had to manage all those parts coming together at the right time to build the completed vehicle. Not only do the parts of the car have to be identified and tracked during assembly, but specific interrelationships between the parts have to be understood.

In this 4-part series, we will cover six SCM design patterns:

    • Design Pattern 1: Paper Forms SCM - determining SCM roles and processes
    • Design Pattern 2: Version Control – automation of base SCM functions (Check-in, Check-out, on-line forms, etc.) to support single state lifecycle CIs (documents, baselines, etc.)
    • Design Pattern 3: Multiple States – support multiple teams (Developers, QA, Customers) working on different views (States) of an Application. Also provides for Management control of CIs and their groupings as they progress through multiple States. A robust relational database that can manage these activities
    • Design Pattern 4: Build and Deployment – ability to support diverse CIs, command line interface (API), interface to a build management tool, scripting environment to direct the activities of a build and deploy. A robust relational database that can manage these activities
    • Design Pattern 5: Parallel Development – advanced user interface including file comparison, version tracking, branching, and merging. A robust relational database that can manage these activities. Still lacking in tools to evaluate the impact of merging.
    • Design Pattern 6: Content Management – Graphics based web interface, large grain SCM, and web site deployment tools

 

This important concept of CM is that it manages components, their state and characteristics over time, as well as their relationship to other elements in the entire configuration—in this example the completed car. CM systems keep track of things (tires, windshields, seats) and their interrelationships to other things (the tire must fit inside a wheel well, the windshield must fit into a sheet metal frame, and a seat must align with anchor points on the car floor) , not just the things by themselves.

In the world of Software Configuration Management (SCM) we see analogous concepts to those in the physical world; we have to bring together many software components to form a software product, we need to understand the interrelationships of those components, their state over the course of a software project, and characteristics over time. We must also know their relationship to other elements in the entire configuration (a software product like a Web Browser). SCM systems keep track of software components and their interrelationships to other software components, not just the software components by themselves.

Software execution environments are much more complex today than they were in the past. In the past there would have been a single computer, a simple input/output device, a keyboard, a monitor and/or printer. During this period SCM tools usually existed on the computer where the software executed and approvals were performed with paper forms.

In today’s complex distributed development environment it is very easy to get caught up with the “bells and whistles” of modern SCM tools. With all the selling hype we experience today it’s also very easy to think that “if I can just select the right tool, then all my SCM problems will go away”. This is absolutely the wrong thing to do! Two major concepts drive any SCM system, no matter if it is a big system or small :

  • Planning - SCM activities must be planned for early in the lifecycle* of a software project. This includes identifying Configuration Items** (CIs), requirements for your SCM system, and personnel to fill SCM roles.

    *Note: A “lifecycle” refers to all the stages of an Application as it progresses from inception to shutdown. I will be dealing with a subset of the term going from change control to production.

    **Note: Configuration Item is an abstract term used to represent the domain of all objects that are known to a SCM system. The primary method by which generic objects become CIs is the Check-in function. CIs could include, but are not limited to, documents, code, makefiles, graphics, etc. Be careful not to confuse other objects that may exist on a computer system but are not known to the SCM system.
     
  • Process - You must create and understand the SCM processes that will drive your SCM system before you can automate their functions.

Most software applications we see today are multi-platform, multi-language, and operate across multiple physical environments – all of which have software that needs to be created, integrated, tested, built, released and managed.  Simple software applications can sometimes get by with simple SCM systems, but with government regulations such as Sarbanes - Oxley, and requirements from other government agencies, as well as your customers, SCM systems tend to require more robust configuration tracking and reporting, even in the simplest of software applications.

The focus of this article is on the use of Software Configuration Management (SCM) and how different types of software design, development, and implementation has driven the functionality and features of the SCM tools we see today. I will discuss the  processes and procedures of various design patterns starting from a simple paper-based design pattern, an automated version control design pattern, moving to more complex multi-State Design Patterns, the hotly-contested parallel development Design Pattern, and finishing with a web-based Design Pattern. By using the Design Pattern analog I hope you will come away with a greater understanding of how SCM works in various situations and what types of SCM functions are needed for those situations.

SCM Forms
This first Design Pattern is based on the use of SCM Forms. It is a very simple Design Pattern that could be used in the following situations:

    • Initial modeling of a SCM system that uses paper forms to drive the processes
    • Simple document version control with no computerized SCM system
    • Simple version control for a simple Application with no computerized SCM system

We will assume that we have a server that houses the CIs that make up an Application or Documentation set. There will be three groups of personnel who have access to this server and will be involved with the execution of this SCM process (See Figure 2 for a flow chart of the forms mentioned in the following section):

    • Developers* –  Responsible for getting approval to make a change to the Application (SCM100, See Figure 3) creating CIs, changing CIs, checking–in CIs to the Server, checking-out of CIs from the Server, filling out Form SCM200 ((See Figure 4) check-out, check-in Log) and getting approval from the Change Control Board (SCM300) on check-in (See Figure 5). For this Design Pattern we will assume that a developer could be a writer if the function of the Design Pattern is to control documents.
    • Technical Team Manager* – Responsible for filling out Form SCM100 ((See Figure 3) Change Control), SCM300 (See Figure 5), approval in SCM100 (See Figure 3), approval of check-in CIs on Form SCM200 (See Figure 4), and approval in SCM 300 (See Figure 5). Works with development/writing teams at the CI integration level.
    • Development  Project Manager* – Responsible for approval in SCM300 (See Figure 5) as well as responsible for the makeup (how the Application is organized) of the Application. This role and the Technical Team Manager may be the same person in a simple documentation situation.

*Note: The roles I have created for this Design Pattern and those that follow are for illustrative purposes only. Your development environment and SCM system/tool may call for other/different roles.

The topology of this Design Pattern is based on the roles defined above and seen in Figure 1.

jjwp_1.jpg

    

Process Flow Diagram

jjwp_2.jpg

Figure 2 shows an overview of how this Design Pattern is going to work. I have also indicated some of the external inputs that might drive a change control which is the start of the SCM process. It may require several iterations to get it right but the flow chart must show where all the forms are going to be used. Think of it as a static map with the forms as the process enablers. This first pattern is simple for ease of use and is possibly a good start to enabling SCM in a small project or even a large one prior to more complex patterns.  Additional complexity will be added as we move through the Design Patterns that follow.

With the hardware topology, roles, and process flow defined lets go through the paper forms I have indicated when you start designing a SCM system.

Form SCM100: Change Control

jjwp_3.jpg

The purpose of form SCM100 shown in Figure 3 is to document change requests, enhancements, or bug fixes related to an Application project or project documentation. This form contains information that is useful to the decision makers who will either approve or reject the change. If the change request is approved it will also be helpful to the developer who will have to make the changes. The Technical Team Manager is responsible for filling out the form. Both the Technical Team Manager and the Application Project Manager must approve the form before it is assigned to a developer to perform the work.

Form SCM200: Check-out / Check-in Log

jjwp_4.jpg

The purpose of form SCM200 shown in Figure 4 is to  record all the CIs that  are checked-in and checked-out of the server to implement a change or to create new CIs. It also acts as a simple version control tool and provides sign-off by the CCB. You would have one of these forms for each change request so that a development team can refer back to them if an audit trail is needed.

Form SCM300: Change Control Board

jjwp_5.jpg

A Change Control Board (CCB) is a group responsible for evaluating and then approving or rejecting proposed changes to existing CIs or new CIs that will be integrated back into the server. The purpose of form SCM300 shown in Figure 5 is to support the CCB process by providing all the necessary information to the CCB members. The SCM300 form is similar to form SCM100 but now it evaluates the return of changed/new CIs to the server. I have also included a reference to the change/new CIs from form SCM200.

So this paper-based SCM system is now complete and ready to try out. As you work through the process of using these forms and seeing where things work and where there are problems, you should document these issues and go back and review the roles and processes. It may take several tries to work out the bugs but it is time well spent. Another output of this Design Pattern is to get all the stakeholders to agree on how you are going to run your SCM system in support of your development processes.

This Design Pattern is simple in comparison to today’s SCM systems/tools, but it has the foundational elements of what any good SCM system/tool must accomplish. However the lack of automation makes this Design Pattern rather cumbersome to use in a production environment. With the computer resources we have today we can improve on this Design Pattern substantially by automating its functions.

Read Part 2 at SCM Design Patterns: Version Control & Multiple States

Read Part 3 at SCM Design Patterns: Build and Deployment

Read Part 4 at SCM Design Patterns: Parallel Development and Content Management


About the Author

Jim Johnston has worked in the IT industry for over 20 years. He has held multiple positions including CAD/CAM programming, applications integration coordinator, manager of a application launch center for testing and integration verification of PC applications, and testing architect for major web systems. Jim has been involved with SCM for over 6 years primarily in the areas of enterprise web applications, retail web sites, SCM process development and J2EE build and deployment methodologies.  

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.