PERFORCE HELIX

Best Practices Checklist:

Software Version Management

More than a set of source files is needed to build a modern software product. To truly excel at
software version management, literally everything that is needed to plan, create, and release a
product will benefit from being under its control. Here’s a checklist of things to look for:

oo Source Code oo Design Documents

Start with the obvious. From there head both upstream Ever make the same design decision more than once? It’s
towards requirements and research, and downstream to build easy to do with large or long running projects. Versioning
and testing. Look for anything that helps shape, create, build, your design docs helps teams discover the chain of reasoning
document, and deploy your product. behind a decision, or even that a pressing issue has already
been resolved, and why.
oo Requirements/Research
The history of your project starts with research and oo Agile Charts and Boards
requirements gathering. For example, if you version the Agile generates a slew of documentation, all of which
personas used to determine requirements and scope, you can deserves a place in your version management tool.
track which exact persona was used to develop which version Fortunately, the initial physical Kanban and other types of
of a specification or design document. management boards are moving into digital equivalents,
where they too can be more easily versioned.
oo Architecture Diagrams
Rarely does an architecture diagram emerge fully formed and oo Graphics
remain unchanged through deployment of a project. Tracking Most applications include icons, logos, and other graphics.
the changes with version management allows you to tie in You need to track both the compressed files built into the
changes to understand emerging facts or new competitive product, and also the original files from the content creation
pressures that affect the evolution of your architecture. tools your designer used to create them. That way there will
be no doubt which evolved version of an original is present in
oo Functional Specifications your final product.
Specifications evolve, just as software does. The specifications
might be considered the user experience architecture of your oo External Code and Licensing
product, and similar benefits from versioning apply to them Many projects use code and other resources from outside
as to the architectural documents just discussed. sources, such as open source code or example code found
online in a forum or social site. Versioning the source along
with the license text or terms of use when adding the code
to your project ensures you have essential information when
planning or reviewing your product’s license for release.
PERFORCE HELIX
Best Practices Checklist

oo Code Review oo Build

Code review is like a mini, temporary branch of version Scripts, procedures and policies all have bearing on creating
management, with a social twist as multiple people weigh in the shippable version of your software. Likely hidden
and discuss. Anything that is created during the code review are highly specific compatibilities between the different
process is information about how your product was built and components. It is also an excellent place to look for
needs to be under version management. unmanaged dependencies. For example, if you build software
for custom hardware, version information about that
oo QA – Issues dependency to a specific version of a chip is very important.
Defect tracking is likely already integrated into your version Not just the build input, but build output and logs should
management system. But what about the search filters used also be versioned.
in GUI tools to track open issues? Excel spreadsheets with
exported data? oo Deployment
Consider that the shippable version of your software is rarely
oo QA – Tests identical to the one your customer uses. Installers typically
When tracking where a bug came from and where it went, adapt settings and components to a specific machine or install
versioning the entire test suite and policies lets you discover base. This means not only installer source code, also installer
which test failed and let the bug escape to a customer. settings, configurations, and options are all ready to come out
of the rain and under the Version Everything umbrella.
oo QA – Tools
Automated Testing and Continuous Integration require
configuration and setup. To reconstruct a product, that
information needs to be versioned in concert with the source
code. Sometimes this won’t be possible (for example, settings
in some tools are not easily exportable).

Perforce Software Inc.

2320 Blanding Avenue, Alameda, CA 94501, USA | Phone: +1 510.864.7400 | Fax: +1 510.864.5340
Email: [email protected] | perforce.com
Copyright © 2015 Perforce Software Inc. All rights reserved. All trademarks or registered trademarks used herein are property of their respective owners.