I remember the first SCMP that I read.  I was new to CM and I felt like I was reading the maintenance procedure for a Chinese tank.  It was filled with all these unfamiliar acronyms and was about as interesting as a software license agreement (which I know you all read).  However, after going through the process of writing a few, the experience has been well worth it.  It has helped me learn a great deal about configuration management and the importance of planning your CM activities.  Besides, I get the distinct pleasure of watching others go through a similar experience as they read one of my SCMP’s for the first time.  I can tell by the tortured look on their face.

What is an SCMP?

Basically your SCMP is where you record your decisions on how you are going to use configuration management for any given project (in this case, a software project).  It should be created in the early phases of the software development lifecycle to define your configuration management process.  Writing this document forces you to answer many questions up front on how you will use configuration management, which will help a great deal later on when you are trying to get code out the door.  It should answer such questions as what the configuration management tasks are and who will perform them.  What is being controlled and how will it be controlled?  How will the status of the controlled items be reported?  What days of the week does the company cafeteria serve the best soups? And so on.  It is also a living document that can change throughout the software lifecycle, but the Change Control Board must approve any changes to it once it goes through its official approval by the group.  What’s the Change Control Board and who’s on it?  Look in your SCMP!  This is another item that should be included.

Why do You Need an SCMP?

I’m sure you’ve heard the old adage “those who fail to plan, plan to fail”.  This certainly applies in this case.  If you don’t have a plan for configuration management, how do you know that it’s being done correctly, or being done at all?  Not having a written plan probably means you are not practicing configuration management at all, or maybe you think it’s being done, but no one on the team even knows what configuration management is.  Lack of a plan could also mean that you’ve either “always done it this way” or you subscribe to the “CM Theory of the Month Club”, depending on who’s in charge.  Groups without a plan are very likely the same ones who miss deadlines and find previously solved errors creeping back into their builds.  If you want to avoid these things, you need to figure out how you are going to do it.  The best place to start is your SCMP.

Another good point about the plan is that the act of writing it is just as valuable as the end product.  As you write your plan, you are forced to consider situations that have never happened and things that you probably should be doing but are not.  For example, is the software library being backed up?  Who’s doing it?  How often?  Has the integrity of the backups been tested?  These kinds of items should be addressed by the SCMP.

Who Writes the SCMP?

Your configuration manager typically authors it, although the whole software team should at least participate in reviewing the document.  After all, they will be the ones who have to follow the process that is going to be defined, so they should have a say in it.  It’s much better to argue about the details during the review process instead of at the eleventh hour before a build.  This will also help a great deal later on when you are trying to get project members to actually follow the process.  They already had their chance to change things, so anyone who resists later on has to face up to the fact that they already gave their approval.

How do You Write an SCMP?

Don’t worry, you don’t have to sit down with a blank piece of paper and just start writing one.  You can always start out with a plan you inherited from another project or start with a template.  If your organization does not have an SCMP template, there are standards you can find online and you can even ask other CM’ers right here on CM Crossroads to share their templates with you.  There have already been threads posted on this topic.  One great example that I found in a thread was a reference to the whitepaper “Configuration Management (CM) Plans: The Beginning to Your CM Solution" written by Nadine M. Bounds and Susan A. Dart. This paper can be found on the Software Engineering Institute at Carnegie Mellon University site at www.sei.cmu.edu. It’s not an actual template, but a great guide to what you should include and how it should be written.

If you were part of a large organization, it would be a good idea to have a work group draft up a template that meets everyone’s needs.  The act of creating a template also helps you to address many CM issues, and it’s scope reaches across a higher level than just a single project.

Once you have a template, you just go through it and see how it’s contents apply to your project’s situation.  It’s a template, after all, and you can add and delete things as you see fit.  One thing to avoid is getting into too much detail about how you do things.  For example, you don’t have to describe the exact process of how a user checks a file out of the source code library.  You should have a separate procedure that describes how a user uses the source code library and the SCM tool, but this document should only be referenced in the SCMP, not spelled out step by step.  The SCMP should cover how changes to the source code library are made, where the library is located, and what the file structure of the library looks like, but not every detail on how it is used.  I personally create separate procedures on topics such as using the SCM tool, building the software, and exactly how change control is implemented.  These documents are all referenced by the SCMP so that a user knows where to look to get the detail, but it keeps the SCMP much shorter and cleaner.  This also allows the called out procedures to be tweaked without having to consult the Change Control Board for every little change, and it allows new users to tackle the detail one document at a time instead of trying to get through one whole document.

What Kind of Things Do I Include?

Reviewing the templates will give you much more information on exactly what you should include, but I’ve covered a few of the highlights below.

To start off, you should have a section that describes what makes up the SCM group and what their responsibilities are.  Usually this includes things like managing the SCM library and the SCM tools used. Then you should have a section that describes the SCM activities which could include how things are identified in terms of versioning schemes, how change control items are identified, how project baselines are created, and so on.  You should have a section that describes the item libraries, like how many there are, where they are located, what kind of retention policies you have, and what the disaster and recovery plans are (or where they can be found).

You should also have a whole section on change control.  How do things change, and how are the changes controlled?  Who is on the Change Control Board and what are their responsibilities?  What kind of tools will be used for change control?  Again, you don’t want to detail out exactly how users perform all of these items, but you do want to explain the methodology behind how these items will be accomplished.

Another important item you include in your SCMP is what objects you are going to control.  You want to have a list of those items, but once again, you don’t want to get into too much detail depending on the item.  For example, you do want to control all source code, but you don’t want to have to list every single source code file in the project.  Instead, you can simply identify them by their file extension.  For example, if you are programming in C++, all files with a ‘.cpp’ extension would have to be controlled.  You want to make sure you include all file extension types in your list, because there are files that you don’t want to control, such as intermediate files that are created by the build.  You should also decide if you are going to control the executables created by the build.  Some prefer this option, but others argue that they are re-creatable so they don’t belong under source control.  Either way, you spell out the way you plan on doing it in your SCMP. You should also list all your critical documents such as your requirements, specifications and project management plan.  Since there usually are not a large number of these documents, it’s a good idea to identify each of them individually.

You also should spell out the status accounting of CM Activities.  I’m not talking about the little old man with the adding machine accounting, but what kind of reports will be run, how often and who will be the recipient?  How will release media be stored and distributed?  What is the release process?  What items will actually be released?

Finally you should have a section on auditing.  What kinds of audits will be performed and how often?  To whom will results be reported.  One item that should be audited is the SCMP itself.  After it has been written, does it contain everything that is required by the organization?  Auditing is most common on projects that are following some kind of discipline such as Software Engineering Institute’s Capability Maturity Model, but they can be handy for any organization that wants to make sure everyone is following the rules, or that the rules are at least clearly defined.

In conclusion, the best way for you to really learn what an SCMP is all about and how it can help you in your Configuration Management duties is to actually write one.  The first attempt might not solve all your configuration management issues, but the experience will get you on the right track to having a better configuration management policy.  A good configuration management policy will then help you to get better results in less time so you have more time to enjoy piña coladas on the beach.

Matthew K. Johnson is a Contributing Editor for CM Crossroads and is a Software Configuration Manager responsible for several commercialization software projects for his Rochester, NY based employer. Mr. Johnson has a BA in Economics and a BS in Computer Science.