September 17, 2007

Using the Workflow

Surround SCM
Surround SCM offers a workflow to give users a clearer view of the state of files. Furthermore, it can be used to marry the source code tool with an existing process in place. This article will show how to use the workflow from a basic peer review code process to a continuous integration process. We will combine simple workflows to create more complex workflows. Finally, we will discuss how to further enhance the workflow. Refer to the Surround SCM user guide for further details on how to set up the states and transitions for the workflow. This article assumes that you already know how to set up a basic workflow. While this example only covers software development processes, the Surround SCM workflow is flexible enough to accomodate other processes as well. [toc]

Basic Review Workflow

The following workflow consists of 6 states used to mirror a basic peer code review. Along with triggers, the peer can be notified of a pending review and check ins and check outs can be prevented if a file is not in the proper state. We don't want a check in if the code has not been properly reviewed, do we?

Defining States

Following are the states used in this workflow: <No State>: Default state provided, usually used for files that will not be in the workflow. New File/Idle: Files in this state have just been added and have not gone through the process yet. Also to be used when files are in an idle state. A separate state was not created for "idle" files in an attempt to keep the workflow as simple as possible. Work in Progress: Files in this state are currently checked out and changes are being made. Needs Review: Files in this state are those that its changes have been saved and sent to a peer for review. Needs Attention: Files in this state have been reviewed by the peer and the changes have been rejected by the peer. More changes are needed. Reviewed: Files in this state are those whose changes have been reviewed and approved by the peer. The file is ready for check in. Checked In, Approved: Files in this state are those whose changes have been approved by a peer and subsequently checked in.

Setting up the Transitions

Once you define the states for the workflow, the next step is to set up the transition. When file is in a certain state, what other state(s) can it move to? The basic flow of the process is as follows: File is added and is in "New File" state. The file is checked out and it immediately goes into a "Work in Progress" state. When changes are finished, the state of the file is changed to "Needs Review". Peer reviews the code and depending on the results of the review, the file is moved into the "Needs Attention" state or "Reviewed" state. If it moves into the "Needs Attention" state, then the developer must make changes according to what the peer found. If the file is moved into a "Reviewed" state, then the file is ready to be checked in. Once the file is checked in, the file is moved into a "Checked In, Approved" state. Figure 1 below illustrates the above transitions set up in Surround SCM.

Figure 1 - State Transitions in Surround SCM

Figure 2 below illustrates the flow between the states described above.

Figure 2 - Basic Peer Review Workflow Diagram

Basic Build Workflow

The following workflow consists of 5 states used to mirror a basic build process. Along with triggers, a build user can be notified of a pending build and check ins and check outs can be prevented if a file is not in the proper state. We don't want a check out of the code while we are getting ready to do a build, do we?

Defining the States

Following are the states used in this workflow: <No State>: Default state provided, usually used for files that will not be in the workflow. New File/Idle: Files in this state have just been added and have not gone through the process yet. Also to be used when files are in an idle state. A separate state was not created for "idle" files in an attempt to keep the workflow as simple as possible. Work in Progress: Files in this state are currently checked out and changes are being made. Ready For Build: Files in this state are those that its changes have been saved and checked in. The files are ready to be included in the next build. Build Started: Files in this state are in included in a build currently in progress. This state lets users know the progress of the build. Build Failed: Files in this state are those who could contain errors that lead to the failure of the build. The file may require changes. Build Success: Files in this state were part of the last successful build.

Setting up the Transitions

Once you define the states for the workflow, the next step is to set up the transition. When file is in a certain state, what other state(s) can it move to? The basic flow of the process is as follows: File is added and is in "New File" state. The file is checked out and it immediately goes into a "Work in Progress" state. When changes are finished, the file is checked in and the state of the file is changed to "Ready For Build". Once the necessary files are in a "Ready For Build" state, the build is started and the files are moved into the "Build Started" state. Once the build finishes, depending on the outcome, the files are moved into a "Build Failed" or "Build Success" state. If it moves into the "Build Failed" state, then the files may be have to be reviewed to see why the build fail and changes maybe needed. Figure 3 below illustrates the above transitions set up in Surround SCM.

Figure 3 - State Transitions in Surround SCM

Figure 4 below illustrates the flow between the states described above.

Figure 4 - Basic Build Workflow Diagram

Combining the Basic Review and Basic Build Examples

The following workflow combines the two basic workflows above. It consists of 9 states, all of which were used in either or both of the two basic workflows outlined above.

Defining the States

Following are the states used in this workflow: <No State>: Default state provided, usually used for files that will not be in the workflow. New File/Idle: Files in this state have just been added and have not gone through the process yet. Also to be used when files are in an idle state. A separate state was not created for "idle" files in an attempt to keep the workflow as simple as possible. Work in Progress: Files in this state are currently checked out and changes are being made. Needs Review: Files in this state are those that its changes have been saved and sent to a peer for review. Needs Attention: Files in this state have been reviewed by the peer and the changes have been rejected by the peer. More changes are needed. Reviewed: Files in this state are those whose changes have been reviewed and approved by the peer. The file is ready for check in. Ready For Build: Files in this state are those that its changes have been saved and checked in. The files are ready to be included in the next build. Build Started: Files in this state are in included in a build currently in progress. This state lets users know the progress of the build. Build Failed: Files in this state are those who could contain errors that lead to the failure of the build. The file may require changes. Build Success: Files in this state were part of the last successful build.

Setting up the Transitions

Once you define the states for the workflow, the next step is to set up the transition. When file is in a certain state, what other state(s) can it move to? The basic flow of the process is as follows: File is added and is in "New File" state. The file is checked out and it immediately goes into a "Work in Progress" state. When changes are finished, the state of the file is changed to "Needs Review". Peer reviews the code and depending on the results of the review, the file is moved into the "Needs Attention" state or "Reviewed" state. If it moves into the "Needs Attention" state, then the developer must make changes according to what the peer found. If the file is moved into a "Reviewed" state, then the file is ready to be checked in. Once the file is checked in, the state of the file is changed to "Ready For Build". Once the necessary files are in a "Ready For Build" state, the build is started and the files are moved into the "Build Started" state. Once the build finishes, depending on the outcome, the files are moved into a "Build Failed" or "Build Success" state. If it moves into the "Build Failed" state, then the files may be have to be reviewed to see why the build fail and changes maybe needed. Figure 5 below illustrates the above transitions set up in Surround SCM.

Figure 5 - State Transitions in Surround SCM

Figure 6 below illustrates the flow between the states described above.

Figure 6 - Basic Build and Review Workflow Diagram

Continuous Integration Example

Continuous integration refers to the process of constantly monitoring changes in a source code environment and doing builds every time a change is detected. How often the system is checked for changes varies and should be adjusted based on the possible amount of changes. In a single developer environment, a build for every change may be appropriate while in a 100 developer environment that would result in too many builds to manage. Surround SCM integrates with such build tools as Ant, and it also integrates with continuous integration tools like Cruise Control. The following is a workflow that could be used in conjunction with these tools. Triggers and the Surround SCM command line interface (CLI) could be used to further tighten the integration.

Defining the States

Following are the states used in this workflow: <No State>: Default state provided, usually used for files that will not be in the workflow. New File/Idle: Files in this state have just been added and have not gone through the process yet. Also to be used when files are in an idle state. A separate state was not created for "idle" files in an attempt to keep the workflow as simple as possible. Work in Progress: Files in this state are currently checked out and changes are being made. Ready For Build: Files in this state are those that its changes have been saved and checked in. The files are ready to be included in the next build. Build Started: Files in this state are in included in a build currently in progress. This state lets users know the progress of the build. Build Failed: Files in this state are those who could contain errors that lead to the failure of the build. The file may require changes. Build Success: Files in this state were part of the last successful build. Test Failed: Files in this state belong to a build that failed tests, such as a unit test. Test Success: Files in this state belong to a build that passed all the tests. Ready For Next Iteration: Files in this state are those that were successfully built and passed all tests. These files are ready for the next iteration of the development process.

Setting up the Transitions

Once you define the states for the workflow, the next step is to set up the transition. When file is in a certain state, what other state(s) can it move to? The basic flow of the process is as follows: File is added and is in "New File" state. The file is checked out and it immediately goes into a "Work in Progress" state. When changes are finished, the state of the file is changed to "Ready For Build". Once the necessary files are in a "Ready For Build" state (or the predefined time has passed since the last build), the build is started and the files are moved into the "Build Started" state. Once the build finishes, depending on the outcome, the files are moved into a "Build Failed" or "Build Success" state. If it moves into the "Build Failed" state, then the files may have to be reviewed to see why the build fail and changes maybe needed. If the files move into a "Build Success" state, then the testing of this iteration can begin. Depending on the results of the tests the file will then move into a "Test Pass" or "Test Fail" state. If the files move into a "Test Fail" state, the files may have to be reviewed for possible errors and repeat the process. If the files move into a "Test Pass" state, then this iteration has completed successfully and the files are ready for the next iteration. Figure 7 below illustrates the above transitions set up in Surround SCM.

Figure 7 - State Transitions in Surround SCM

Figure 8 below illustrates the flow between the states described above.

Figure 8 - Continuous Integration Workflow Diagram

Figure 9 below illustrates the flow of the workflow with the peer review states added.

Figure 9 - Continuous Integration with Review Workflow Diagram

Enhancing the Workflow

Surround SCM offers other tools to help enhance the workflow further.

Custom Fields

Custom fields are provided as meta data for files and Surround SCM. Use custom fields to assign files to users, set deadlines for changes or further categorize your files. Please refer to the Surround SCM documentation for further details on Custom Fields.

Using the Command Line Interface (CLI)

Surround SCM has a command line interface that offers most of the commands available throught the GUI client. Use the command line interface to automate state changes in the workflow using the "set state" command. Use this command with your continuous integration and build tools to change the state of files based on the result of the build and unit tests. Use the 'mkbranch' command to create a snapshot branch after each successful iteration in the continuous integration workflow. Please refer to the Surround SCM documentation for further details on the Command Line Interface. To view help on each command at the terminal window (command prompt) type "sscm -h" + {ENTER} to see a list of all the commands and type "sscm <command name> -h" + {ENTER} to view help on a specific command.

Triggers

Surround SCM offers triggers as a way to further extend the application. Use triggers to enforce the workflow, perform additional actions, and to notify team members. Please refer to the Surround SCM documentation for further details on Triggers.

Automatically Change States on File Events

Use the "setstate" command mentioned above in conjunction with triggers to automatically set the state to "work in progress" when a file is checked out. Use the "set state to" action in triggers to automatically change the state of a file upon check in.

Enforcing the Workflow

Here is an example of enforcing the workflow through triggers by using the "prevent event with message" action . In the Basic Review Worflow, create the following trigger to ensure that a file is not checked in unless it is in the "Reviewed" state: Trigger applies to files in branch [WysiCorp] and in repository [WysiCorp] [recursively] and file state [is not in list] [Reviewed] -- before an event on a [Check in] -- Prevent the event with message "File can not be checked in unless it is in a Reviewed state!"

Keeping Team Members Informed

Another great feature of triggers is the ability to send e-mails. Here is an example of using triggers to notifiy a user of a change in state of a file. In the Basic Build Workflow, create the following trigger to notify a user that a file has entered the "Ready to Build" state: Trigger applies to files in branch [<all branches>] and in repository [WysiCorp] [recursively] -- after an event when resulting file state [is in list] [Ready For Build] -- Send emails to "BuildUser"

Other Enhancements and Extensions

This blog contains several Surround SCM articles that can be used in conjunction with these examples. From instructions on how to integrate with build tools to how to use triggers to automate a build process, there is a wealth of knowledge available to you to get the most out of Surround SCM. Also, remember that Seapine Software offers consulting services that could help you deploy the best solution for your situation.