Overview
WhatSource control refers to the process of tracking changes across types of “source code” that can be used to generate the application. Versioning is a more general term that refers to keeping snapshot revisions of each major version of a particular resource. For more information, including a reference to many of the terms you will see here, see http://en.wikipedia.org/wiki/Revision_control.
Keeping track of changes, and why they were made, is important for any project. It supports:
- The original work creator, to know what changes were related to a given piece of functionality.
- Other developers in a collaborative work, who may be working on different parts of the same piece of code, to avoid conflicts and overwriting each other.
- Other users who may have to pick up the original work and extend / maintain it.
You should use source control anywhere you have code. In addition, it is usually a good idea to keep all major versions of any other types of documents (for example, datasheets, contracts), especially if they are published or distributed in some form. Oracle CPQ does not have versioning built in, but there are a variety of other tools that you can use.
The first step is to get a good version control system. There are a number of these, many of them free. If you have a standard within your organization, that is usually the best one to use. If you do not have a standard that your Oracle CPQ admins are already using, here are a few that you can try:
- Git: http://git-scm.com/ - Distributed Version Control, very good Windows client at http://code.google.com/p/tortoisegit/
- Mercurial: http://mercurial.selenic.com/ - Distributed Version Control, very good Windows client at http://tortoisehg.bitbucket.org/
- Subversion: http://subversion.tigris.org/ - Centralized Version Control, very good Windows client at http://tortoisesvn.net/
- Dropbox: http://www.dropbox.com or Box: http://www.box.com are good options for document snapshots, with the added benefit that you can easily use those services to share documents with other users.
Next, you need some policies and guidelines. This is really dependent on your development procedures, but here a few recommended practices:
-
Version control everything that you can.
Similar to backup, if you neglect to version control of one script or document, that will probably be the one that you will want history of at one point. In CPQ, you would definitely want to control at least the following: BML, XSL, CSS, JavaScript. You may also want to include things like Data Tables (which are easily exported as CSV and can be versioned very efficiently).
-
Check in often.
The smaller the individual change sets are, the easier it will be to determine what the purpose of each one is. A good rule of thumb is, commit your changes whenever you click Apply or Update to save your changes in CPQ. One of the benefits of a distributed version control system like Mercurial is that you can do this without impacting other users, since commits are local by default.
-
Pay especially close attention to scripts that more than one user are working on (common configuration rules or commerce pricing functions, for example).
If you are a developer in one of those scripts, and you know that other users are working on it, make sure to GET the latest version before making any modifications of your own, rather than reusing a version you have saved offline.
-
Make sure your system automatically tags changes with the user that makes the change, or make it a matter of policy to do so.
Usually, when you want to know what a piece of code does, the best person to ask is the original developer, and this makes it much easier to know who that was.
-
If your system allows it, add a comment to each check-in / commit in order to track what purpose the changes are meant to address.
This is a good place to put a reference to a case, requirement, or design feature, that the code implements. Internally, we use Salesforce.com Cases to track almost everything we build, so we have a standard field for case number that automatically links to the Case, but a simple text comment works as well.
-
Ensure that you can revert to earlier versions, and know how to do so.
This is especially important in a crisis situation, when you want to be able to recover quickly and efficiently, and often a revert is the best way to accomplish this.
Ensure that everyone in your organization that touches the code follows the source control policy, if at all possible. This is true for all policies that you make, but it is especially important for source control because that system is the source of record for all of the changes that you make, and may save you from having to recreate a lot of lost work when somebody accidentally overwrites what you did.
Some elements (for example, Attributes, Simple Rules) are not easy to put under version control because they are not expressed as text. In practice this rarely creates an issue, since these components are fairly simple to modify / delete / recreate, but if you are concerned about this, there are a few steps you can take:
- Keep a change log of all changes made, including Attributes and Rules, with enough detail to be able to recreate them if needed. The Administration Logs can be useful as a starting point, which you can embellish as necessary. For more information, see the topic Administration Logs.
- Periodically download and store “snapshots” of the full Configuration / Commerce Process using the Bulk Upload / Download feature. For more information, see the topics Bulk Uploads and Bulk Downloads.
