SCM Best Practices: Determining Which Practices Are Best for You

[article]
Summary:
What's Best? What are industry best practices for Software Configuration Management (SCM)? Which best practices are best for your project and for your organization? How should these best practices be applied or implemented to solve your SCM problem domain? Is your project or organization prepared to use SCM best practices? Let's examine a collection of SCM best practices.

What's Best? What are industry best practices for Software Configuration Management (SCM)? Which best practices are best for your project and for your organization? How should these best practices be applied or implemented to solve your SCM problem domain? Is your project or organization prepared to use SCM best practices? Are there good best practices and not-so-good best practices, or are some SCM best practices better than others? What should you know before applying SCM best practices to your project or to your organization? Let's examine a collection of SCM best practices.

Where's the Value?
I have always believed in the installation of SCM as a critical and much-needed process during early stages of the development or product lifecycles. That is, recognizing its

What's Best? What are industry best practices for Software Configuration Management (SCM)? Which best practices are best for your project - for your organization? How should these best practices be applied or implemented to solve your SCM problem domain? Is your project or organization prepared to use SCM best practices? Are there good best practices and not-so-good best practices, or are some SCM best practices better than others? What should you know before applying SCM best practices to your project or to your organization? Let's examine a collection of SCM best practices.

value and importance during the early stages of planning when the project manager is developing the project plan. A good understanding of what is to be built, the requisite resources, and the infrastructure needed to support product development is a good start in such planning. Knowing when software baselines are to be established and where they will be located are very important. Insight of the skills needed to support the development environment and the resources that will be required during each phase are key. The project must know how (and where) all product components and their relationships to other products will be managed and controlled. A change control authority must be identified. Responsibilities and roles of the SCM group must be defined and assigned. These are some of the activities and tasks that must be identified upstream - before any requirements are gathered, managed, defined, and developed - before design activities - and before any development work begins.

Examples of SCM Best Practices

So, what are these "SCM best practices?" Let's examine some institutionalized, recognized, and proven best practices in use.

According to the AIRLIE Software Council [1]:

  • Make CM everyone's job
  • Create an environment and engineering process that enables CM
  • Define and document the CM/engineering process, then select the tool set (automation) to support the process
  • The CM staffing should consist of individuals with technical expertise to support the development and maintenance of the product
  • The CM plan and procedures need to be developed and documented in the same way a software development plan (or project plan) is created at the initial stages of a project
  • Identify and store work products in a secure repository
  • Control and audit changes to work products
  • Organize work products into versioned components
  • Create baselines at project milestones
  • Record and track requests for change
  • Organize and integrate consistent sets of versions using activities
  • Maintain stable and consistent workspaces
  • Support concurrent changes to work products and components
  • Integrate early and often
  • Ensure reproducibility of software builds
  • Workspaces (where developers build, test, and debug)
  • Don't share workspaces
  • Don't work outside of managed workspaces
  • Don't use jello views
  • Stay in sync with the codeline
  • Check in often
  • Codelines (the canonical sets of source files)
  • Give each codeline a policy
  • Give each codeline an owner
  • Have a mainline
  • Branches (variants of the codeline)
  • Branch only when necessary
  • Don't copy when you mean to branch
  • Branch on incompatible policy
  • Branch late
  • Branch, instead of freeze
  • Change propagation (getting changes from one codeline to another)
  • Make original changes in the branch that has evolved the least since branching
  • Propagate early and often
  • Get the right person to do the merge
  • Builds (turning source files into products)
  • Source + tools = product
  • Check in all original source
  • Segregate built objects from original source
  • Use common build tools
  • Build often
  • Keep build logs and build output
  • Process (the rules for all of the above)
  • Track change packages
  • Track change package propagations
  • Distinguish change requests from change packages
  • Give everything an owner
  • Use living documents

According to Anne Mette Jonassen Hass [2]:

  • Establish Baselines
  • Identify Configuration Items
  • Establish a CM System
  • Create or Release Baselines
  • Track and Control Changes
  • Track Changes
  • Control Changes
  • Establish Integrity
  • Establish CM Records
  • Perform CM Audits

Cisco [3], the hardware manufacturer recommends the following:

  • Create standards
  • Software version control and management
  • IP addressing standards and management
  • Naming conventions and DNS/DHCP assignments
  • Standard configuration and descriptors
  • Configuration upgrade procedures
  • Solution templates
  • Maintain documentation
  • Current device link and end-user inventory
  • Configuration version control system
  • TACACS configuration log
  • Network topology documentation
  • Validate and audit standards
  • Configuration integrity checks
  • Device, protocol, and media audits
  • Standards and documentation review

Stephen Berczuk and Brad Appleton [4] assert, "Although there are many "best practices" for SCM, to use them effectively, you must understand how they relate to other practices you use and the environment in which you use them."

There are several "best practices" listed by Brad Appleton on his website [5]:

  • SCM Patterns
  • Agile SCM
  • Branching Best Practices
  • Build Reproduction Best Practices
  • Workspace (development "sandbox") Best Practices
  • ClearCase Practices
  • Although not always listed as best practices, the application or implementation the following critical success factors for SCM could certainly help to ensure project success:
  • Senior management support
  • SCM planning
  • Change control and escalation procedures
  • Simple practices and tools
  • Private workspaces
  • Codeline policies
  • Communications
  • Prudent branching and frequent merges
  • Intelligent builds

Senior management support: That is, nothing succeeds without their support! Senior management provides the resources, serves as liaison between executive management and staff, and must be in the communication loop.

SCM planning: Should there be a SCM Plan or just SCM planning? SCM planning is performed first at the project level, and then it's communicated throughout the project. If a SCM plan is used, it must be meaningful, must be revised after each phase, and should be in sync with organizational planning.

Change control and escalation procedures: Must be well documented, enforced by the Project Manager and supported by all levels of management; cannot hinder the project team; must be effective; must be efficient; and must be consistent and repeatable.

Simple practices and tools: Practices should cause good things to happen and should be communicated and understood. Tools should be easy to use and pragmatic, and should enhance communication and reduce rework.

Private workspaces: These are developer areas that must contain:

  • Source code being edited
  • Locally-built components
  • Objects that cannot or will not be built
  • Built objects for all the code in the system
  • Configuration and data needed to run and test the system
  • Build scripts
  • Information identifying versions of all components in the system
  • Codeline policies: Brief "rules of the road" that include:
  • The kind of work summarized by the codeline, such as development, maintenance, or a specific release, or function
  • How and when elements should be checked in, checked out, branched, and merged
  • Access restrictions for certain individuals
  • Import/export relationships are (is) the:
  • o Names of the codelines it expects to receive changes from, and the codelines it needs to propagate changes to
  • o Expected activity load and frequency of integration
  • o Duration of work or conditions for retiring the codeline

Communications: That is:

  • Work closely with the development team
  • Attend staff meetings
  • Know what's happening
  • Publish schedule changes
  • Announce implementation of changes
  • Be a coach and mentor
  • Be a friend - not an inconvenience or bottleneck

Prudent branching:

  • Use a simple branch model
  • Branch only when necessary
  • Do not copy when you mean to branch
  • Branch on incompatible policy
  • Branch late
  • Branch instead of freeze
  • Never branch to avoid integration

Intelligent builds:

  • Check in all original source
  • Segregate built objects from original source
  • Use common and simple build tools
  • Use a centralized build process
  • Build often
  • Keep build logs and build output

Conclusion

The SCM best practices examples listed in this article are not all-inclusive. That is, there are many other activities that can be termed as best practices. Much has been written and said about SCM best practices and a significant number of those practices are critical to the success of a project and the quality of the product or products being built. However, we need to keep in mind several things to ensure such practices remain in proper perspective. First, best practices are products of empirical experience. That is, a process or practice that has been used repeatedly and successfully by an organization can be considered as a best practice. Second, an automated solution is not always a best practice. If your SCM processes adversely affect the productivity of the development group or become a bottleneck, then a tool will only serve to automate those chaotic processes - making them occur more efficiently. Finally, the application of common sense should prevail. The use of logical, pragmatic practices in the execution of SCM tasks to produce strategic work products and conduct essential SCM activities should be the norm. The following are guidelines (or best practices) for successful SCM practitioners:

  • Keep the SCM system easy; otherwise it won't be used
  • Configuration items should exist in the SCM system in one place only
  • Never delete anything from the SCM system - you can move it, but never delete it
  • A properly designed SCM system will solve the development problems first - downstream problems will automatically be solved in development
  • Any build that is not fully automated is risky and costly
  • All on-line work products should be managed by the SCM system
  • Adding more process will never solve a SCM problem - a little process is necessary; too much process is anti-work
  • Backups must be performed - if you lose a repository, you'll probably lose your job
  • Keep things simple!!!

References

[1] The Airlie Software Council - 2001; (http://www.spmn.com)

[2] Anne Mette Jonassen Hass, Configuration Management Principles and Practice, Addison-Wesley; 2003

[3] Cisco Systems - Configuration Management: Best Practices White Paper

[4] Stephan Berczuk and Brad Appleton, Software Configuration Management Patterns, Addison-Wesley, 2003

[5] Brad Appleton website 


Dick Carlson is a process architect with more than 20 years of IT and software engineering experience that includes software development, software engineering training and mentoring, development and implementation of software/system lifecycle methodologies, software configuration management, software project management, software quality assurance, and software process improvement. Dick has trained and mentored teams and individuals on efficient techniques applied to SCM activities, project management, requirements management and development, risk management, business modeling, and business re-engineering. He has also implemented software process improvement initiatives preparing organizations for SEI CMM compliance. Dick is the current VP of Education with the Association for Configuration and Data Management (www.acdm.org) and can be reached at [email protected].

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.