SSW Rules to Better Source Control with TFS

Do you know the benefits of using source control?

Source control is your backup of your code, as well as your change history to track changes.

With the source control (we use TFS), we can share project code and cooperate with other team members. Using it allows us to track changes, compare code and even roll-back if required. Moreover, it keeps our code safe that is the most important.

However, the best use is the blame game. You don't just fix code, you see who broke it, fix it, and then let them know.

Figure: Viewing the changes in source control on each individual file is ok

Figure: We can select different changesets and compare the changes

Figure: We can select different changesets and compare the changes. Blue = modified, Green = addition, Red = deletion

Figure: Right clicking on a file and selecting Annotate to view the history on a segment basis is much better

Figure: Using annotate is great. It allows us to find the coder who made the breaking changes, to understand his thoughts before deleting/changing his or her code.

Figure: Annotation is great, but it gets even better when one click gives you the 'check in comment' and the 'work item'

Do you know the right source control to use?

SSW uses and recommends Microsoft Team Foundation Server (TFS) as a source code solution.

Figure: Microsoft Visual Studio Team System

Here are some of the reasons why:

• Checkin policies
• Integrated Work Items and Source control
• Visual Studio IDE integration
• Code Metrics
• HTTP access via webservices
• Integrated Build Server

We also use Subversion (SVN) and Visual Source Safe (VSS) as needed

Are you very clear your Source Control is not a backup repository?

Only check-in code that is compiling and unit tests are working.
Note: If you are not finished working:

• TFS put changes into shelveset
• SVN put changes into sandbox / branches

Do you know the minimum builds to create on any branch?

When creating projects one of the only ways that you have of proving that it works and is a viable solution is to build it. It is easy for a developer to build and test a solution locally, but this doesn't prove that a solution will compile in another environment. So how do you make sure the project contains everything it needs for deployment? The answer is build servers. These build servers take specific code away to another computer and build it there.

You should always have three builds on your team project. These should be configured and tested using an empty solution before you write any code at all.

Figure: Three builds named in the format [TeamProject].[AreaPath]_[Branch].[Gate|CI|Nightly] for every branch.

These builds should use the same XAML build workflow; however you may set them up to run a different set of tests depending on the time it takes to run a full build.
• Gate - Only needs to run the smallest set of tests, but should run most if not all of the Unit Tests. This build is run before developers are allowed to check-in.
• CI - This should run all Unit Tests and all of the automated UI tests. It is run after a developer check-in and should also include a deployment to a test server.
• Nightly - The Nightly build should run all of the Unit Tests, all of the Automated UI tests and all of the Load and Performance tests. The nightly build is time consuming and will run but once a night. Packaging of your Product for testing the next day may be done at this stage as well.

Figure: You can control what tests are run and what data is collected while they are running.

Note: We do not run all the tests every time because of the time consuming nature of running some tests, but ALL tests should be run overnight.
Note: If you had a really large project with thousands of tests including long running Load tests you may need to add a Weekly build to the mix.

Figure: Bad example, you can't tell what these builds do if they are in a larger list

Figure: Good example, you know exactly what project, branch and type of build these are for.

(Before starting) Do you follow a Test Driven Process?

Never allow a situation where a developer can check out code and the code does not compile – or the unit tests are not all green. This is called “breaking the build” and the punishment in our office is 20 push-ups and fixing broken links for an hour!

Bad Process

1. Check out
2. Compile
3. Develop
4. Compile
5. Check In

A Bad Developer

Figure:Before you start cooking prepare all your ingredients (aka before you start coding, "Get Latest" the right way)

Good Process

1. Get latest
2. Compile
3. Run Unit Tests
4. If Tests pass then start developing
5. Check out
6. Develop
7. Compile
8. Run Unit Tests
9. Get Latest (Always do a Get Latest before checking in as code you didn't change could break your code)
10. Compile
11. Run Unit Tests
12. Check In if all tests passed
13. Wait for gated check-in (GC) to complete
14. Reconcile your workspace if it was successful
15. Check that Continuous Integration (CI) build was successful(If GC was skipped)

A Good Developer

Note: You should have both a Gated-Check-in (GC) and a Continuous Integration (CI) build on every branch.

(After work) Do you only check-in code when it has compiled and passed the unit tests?

Too many people treat Source Control as a networked drive. Don't just check-in when the clock ticks past 5 or 6 o'clock. If code doesn't pass its unit tests or won't even compile put your code in a shelveset

Figure: Put your dishes straight in the dishwasher otherwise you leave a mess for others (aka "Check in" the right way otherwise you give other developers problems)

Other recommendations have included using //TODO or commenting the code out. However we recommend avoiding this practice as it increases the risk that the code is forgotten about.

Note: Having gated check-ins will help prevent this from happening.

Note: A useful tool is TFS Auto Shelve - Protect your code by guaranteeing your pending changes are always backed up to the TFS server.

(Check-in before lunch and dinner) Do you work in small chunks & check in after completing each one?

Frequently developers work on long or difficult features/bugs and leave code checked out for days or worse still, weeks.

1. What happens if your laptop hard drive dies?
2. What happens if you call in sick?
3. How can you pair program if not sharing your changesets?

Figure: Eating one big meal every three days gives you a bellyache... (aka check in small portions regularly, one large check-in after a few days will give you a headache)

That's why source code should be checked in regularly. We recommend a check-in:

• Immediately after completing a piece of functionality, where the code compiles and passes the unit tests
• Before lunch or dinner
• Before leaving your workstation for an extended period of time

If the changes would break the build or are in a state that cannot be put into the main trunk, then this code should be put into a shelveset (sometimes referred to as 'sandbox') in source control.

Another good reason to check-in regularly is that it makes it easier to merge your changes with other developers. If all developers check-in lots of changes in one go, you will spend a lot of your time resolving conflicts instead of doing work.

TIP: How can you enforce regular check-ins? Monitor them using a report to see who has not checked in.

Do you enforce comments with check-ins?

Team System is great, but there are some standard features in other source control systems that aren’t available. One of the glaring omissions is enforcing comments when checking in code. Without comments, some of the other built in features like History become redundant without comments.

Figure: Bad Example: No Comments against the check-ins we don’t know what changes were made in each revision

Figure: Good Example: Now we can pin point which revision a particular change has been made

To enforce this behaviour, you will need to:

1. Install Team Foundation Server Power Tools using the Extension Manager in Visual Studio

   

   Figure: Opening the Extension Manager in Visual Studio

   

   Figure: Installing TFS Power Tools from Visual Studio's Extension Manager

2. Right click the Team Project in Team Explorer > Team Project Settings > Source Control



3. Select the Check-in Policy tab
4. Click Add
5. Select the Changeset Comments Policy

Now the next time someone checks-in some code, they are forced to enter a comment.

Do you enforce work item association with check-in?

One of the big advantage of using TFS is end to end traceability, however this requires the developer to do one extra step to link their code (changeset) with requirements (work items). Code is the body of software, while user requirement is the spirit. Work Item association feature helps us to link the spirit and body of software together. This is especially useful when you trying to identify the impact of a bug in term of user requirements.

Figure: Bad Example: No work item is associated with changeset

Figure: Good Example: No work item is associated with changeset

In order to achieve this, developers need to choose the Work Item tab when check-in and "associate" code with a related work item.

Figure: Associate Work Item with Changeset

As the project administrator, you can take one step further to enable "Work Item Check-in Policy" to enforce this rule in your team.

Figure: Work Item check-in policy

Do you know which check-in policies to enable?

Check-in policies are a great tool to enforce quality code before it hits your source control repository. SSW recommends that the following check-in policies be enabled by default on your project:

1. Changeset Comments Policy - To enforce that all check-in contain comments
2. SSW Code Auditor - To enforce coding standards and best practices before check-in
3. Testing Policy - To enforce that unit tests should all pass before code can be checked-in

To enable these policies:

1. Right click the Team Project in Team Explorer > Team Project Settings > Source Control
2. Select the check-in policies above
3. Click OK

Figure: Chose check-in policies in TFS

Do you know the comment convention you should use?

New, Bug or Refactor should be the prefix.
Here are some examples:

• New P112: Added a new control for DateOfBirth
• Bug P113: Fixed validation to now allow US dates
• Refactor: Moved the email regex from inline to a resource file

Do you know the best Project/Version conventions?

Creating a solution and having it maintainable over time is an art and not a science. I like being pedantic and having a place for everything, no matter how small.

For setting up the Areas to run Multiple projects under one solution see my post on When should I use Areas in TFS instead of Team Projects and for an explanation of branching see Guidance: A Branching strategy for Scrum Teams.

Whenever I setup a new Team Project I implement the basic version control structure. I put "readme.txt" files in the folder structure explaining the different levels, and a solution file called "[Client].[Product].sln" located at "$/[Client]/[Product]/DEV/Main" within version control.

Developers should add any projects you need to create to that solution in the format "[Client].[Product].[ProductArea].[Assembly]" and they will automatically be picked up and built automatically when you setup Automated Builds using Team Foundation Build.

All test projects need to be done using MSTest to get proper IDE and Team Foundation Build integration out-of-the-box and be named for the assembly that it is testing with a naming convention of "[Client].[Product].[ProductArea].[Assembly].Tests"

Here is a description of the folder layout; this content should be replicated in readme files under version control in the relevant locations so that even developers new to the project can see how to do it.

Figure: The Team Project level - at this level there should be a folder for each the products that you are building if you are using Areas correctly in TFS 2010.

You should try very hard to avoid spaces as these things always end up in a URL eventually e.g. "Code Auditor" should be "CodeAuditor".

Figure: Product Level - At this level there should be only 3 folders (DEV, RELESE and SAFE) all of which should be in capitals.

These folders represent the three stages of your application production line. Each of them may contain multiple branches but this format leaves all of your branches at the same level.

Figure: The DEV folder is where all of the Development branches reside.

The DEV folder will contain the "Main" branch and all feature branches is they are being used. The DEV designation specifies that all code in every branch under this folder has not been released or made ready for release. And feature branches MUST merge (Forward Integrate) from Main and stabilise prior to merging (Reverse Integration) back down into Main and being decommissioned.

Figure: In the Feature branching scenario only merges are allowed onto Main, no development can be done there.

Once we have a mature product it is important that new features being developed in parallel are kept separate. This would most likely be used if we had more than one Scrum team working on a single product.

Figure: when we are ready to do a release of our software we will create a release branch that is then stabilised prior to deployment.

This protects the serviceability of our released code allowing developers to fix bugs and re-release an existing version.

Figure:All bugs found on a release are fixed on the release.

All bugs found in a release are fixed on the release and a new deployment is created. After the deployment is created the bug fixes are then merged (Reverse Integration) into the Main branch. We do this so that we separate out our development from our production ready code.

Figure: SAFE or RTM is a read only record of what you actually released. Labels are not immutable so are useless in this circumstance.

When we have completed stabilisation of the release branch and we are ready to deploy to production we create a read-only copy of the code for reference. In some cases this could be a regulatory concern, but in most cases it protects the company building the product from legal entanglements based on what you did or did not release.

Figure: This allows us to reference any particular version of our application that was ever shipped.

In addition I am an advocate of having a single solution with all the Project folders directly under the "Trunk"/"Main" folder and using the full name for the project folders..

Figure: The ideal solution

If you must have multiple solutions, because you need to use more than one version of Visual Studio, name the solutions "[Client].[Product][VSVersion].sln" and have it reside in the same folder as the other solution.
This makes it easier for Automated build and improves the discoverability of your code and its dependencies.

Do you label your versions and releases in Source Control?

TFS takes labeling to a new level unlike VSS which was a point in time label. TFS labels each file based on their changeset version. You can then get code as it was when you labeled the source.

Labeling a release is a good way to go back to a version and generate a compiled version. If you wanted to develop an older version then you would create a branch instead (of course you can create a branch off a label)

Figure: Get a specific version in TFS based on a label

Do you know how to structure your version numbers?

• Major - rarely change - only with major upgrades, new platform - (e.g. office 2007)
• Minor - new features / release (customer facing) - 3 months
• Revision - starts at 0, in ideal world, we have 0. Emergency maintenance or security patches to the customer
• Build - internal build number for QA to differentiate (auto updating)

Do you check-in all files?

When working on a task spanning multiple files, do not check-in only one or two of the files, this leads to the problem of partial check-ins where references to new classes or methods are unavailable because they are in the files that haven't been checked in. So either, check-in all the files you are working on or none at all if you aren't finished working on the task.

1. Make Visual Studio remind you to check code in

   In Microsoft Visual Studio. NET sharing project code can be configured by ticking the two checkboxes on top, in Options (from the Tools menu) as shows below.

   

   Figure: Check-in files automatically the 2nd checkbox is very important so you get reminded to check-in your project when closing VS.NET. You know how frustrating it is when you want to fix an application and all the files are checked out by some one else!

   What about VB6 applications ?
   In Visual Basic 6 this is done by going through Tools -> Source Safe -> Options and setting it as shown in the diagram below.

   

   Figure: You can also check-in automatically in VB6

   What about Access applications ?
   We also use VSS for Access projects. Access 2000 had problems with MDBs (not ADPs) but Access 2003 works fine with both. The only thing you have to be careful of is that if a form is not checked out, it still lets you modify the form, but when you close the form, it rolls back to the VSS version and you lose all of your changes.

   

   Figure: You can also check-in automatically in Access

   

   Figure: All the basic functions are easily accessible.

   Note: Using VSS in Microsoft Access has a few limitations, most significant of which is the inability to reattach to VSS projects.  Once you have detached from a VSS project, you will need to create a new VSS project in order to place the Access application back into VSS.

   What about SQL Server Databases?
   We save the scripts of every SQL Server schema change in Source Control.

Do you use shared check-outs?

In conjunction with regular check-ins, files in source control should never be locked unless absolutely necessary. Use either 'Unchanged - Keep any existing lock' - or 'None - Allow shared checkout'.

Only use 'Check Out - Prevent other users from checking out and checking in' when checking out binary files e.g. Word documents or third party compiled dll’s. (This will be the default this will be the selected option due to the inability for binary files to be merged on check in.)

Figure: Correct checkout settings at the file level - don't lock files

Do not enforce single check-out at the project level - make sure the 'Enable multiple check-out' option is ticked under Team Project Settings, Source Control.

Figure: Correct check-out settings at the team project level - enable multiple check-out's.

Do you have a report to see who has not checked in?

Managers should regularly check to see if developers are committing their changes into source control. In TFS you can only get a status by manually looking at each project or running "tfs status" command. A great tool is Attrice Team Foundation SideKicks which can display the status of all users and projects

Figure: Use TFS Sidekicks and search for files older than 48 hours to find the naughty devs

Suggestion for TFS Sidekicks: Add a button to "Email all people their shame list"... showing their files that are still checked out (until then I do it manually)

Tip: If old edits are no longer required, or the workspace is no longer current, you can undo changes by highlighting the files you want to undo and clicking the Undo Pending Change button.

Figure: Use TFS Sidekicks to undo old checkouts by selecting them and clicking "Undo"

Do you only check out the files that you need?

Checking out files that you do not plan to modify could confuse other developers on what is currently being worked on , as well as making it difficult at check-in time to see what files you actually have modified.

Do you avoid limiting source control to just code?

You can spend valuable developer time on every part of a project. The bulk of time is normally spent on coding up .cs, .vb, .resx and .aspx files. However, you could potentially have the following happen if you do not include other files in source control:

• lose work
• lose old versions of work
• have work overwritten

In particular, you should make it as easy as possible to see who changed what and who deleted what and allow a simple rollback to previous versions of non-code files. Files you should put in source control include:

• XSL files
• Word documents
• Excel Spreadsheets
• Visio Diagrams
• HTML files
• Image files, Flash animations and psd files  (yes this takes room in your source control database - but we still want to be able to revert to an old version easily)

Things you don't store are:

• Video files eg. avi
• Installers eg. .msi

Do you include original artworks in Source Control?

Your original digital artworks are part of your asset and they also need to be managed accordingly. However many organizations fail to realize this and issues starts to arise when you need to roll back your images only to discover that the designer has overwritten the old images or worse, the image was designed spontaneously and the original design was exported to a .jpg or .gif without the original design being saved! Including your original artworks in SourceSafe can be handy in case of hard drive failures or accidental deletions.

Figure: Include your original artworks in Source (eg .PSDs in Source Control)

We chose to exempt uncompressed video files as they tend to have large footprints and potentially cause delays in productivity. It is highly recommended that you have a separate backup procedure for these files.

Do you know how to rollback changes in TFS?

Whilst working on a new feature all morning I’ve realised that this isn’t going to work out. I need to revert back to what the code was this morning before I touched it. But how?

There are two ways to do this:

1. If you haven’t checked in any files since you started modifying them then the process is simple:
   • Right click your solution and Undo Pending Changes

   

2. If you aren’t so lucky and have made some commits along the way then the only option is to use the Rollback command.
   • To use this you will need to install Team Foundation Server Power Tools v1.2
   • Find the revision before you started checking code in using the History command

   

   Figure: The last revision before Tristan made changes was 5367

   • Open the Command Prompt in your current working directory and type “c:\Program Files\Microsoft Team Foundation Server Power Tools\tfpt.exe” rollback /changeset:5367

   

   • Click Yes and the rollback will proceed

It would be nice if there was a GUI for this tool so that I can just right click and select rollback. See Better Software Suggestion – TFS

Do you configure your TFS to be accessible from outside the network?

It is important to have source control available to you wherever you are, so that means than VPN access is not enough. This is because sometimes when you are working on-site, the client may have strict network policies that block VPN or even port 8080 is blocked.

Tip: You can slove this with TFS Extranet Support:

• TFS SP1
  This feature called "Extranet Support" was added way back in TFS 2005 SP1 as per Stuff in the pipe for Team Foundation Server
• A domain name or IP address forwarded to TFS (eg: tfs.your-domain.com)
• Port 8080 (this is port that TFS uses for source control)
• Firewall/Router rule (ideally)

Yes Port 8080 will work in most cases but not on the strictest networks, where only Port 80 is allowed.
Then you have to use port forwarding via a firewall/router rule (recommended) to forward port 80 to the TFS port, while in this way, you would lose the TFS SharePoint Portal and Reporting Services.

Figure: Rule to forward port 80 to the TFS port

Do you configure your Team System Web Access to be accessible from outside the network?

If you have Team System Web Access installed and you need to access it from wherever you are, you can configure a port to be forwarded to the server where Team System Web Access is installed, eg: tfs.your-domain.com:8090.

Figure: Visual Studio Team System Web Access Power Tool

Do you use SSW Agile Template for SSW project?

We have developed a customized TFS team project template which includes customized reports like SSW Release Plan Report and SSW Project Progress Report. You can get SSW Agile Template from here SSW for Agile Development Template

Follow the documents in the download package to create new team project or upgrade from existing team project in TFS.

Do you use the Windows Explorer Integration

1. Install the TFS Power Tools
2. When you install this, make sure you do a 'Custom Install', and select the 'Shell Integration' option (this is off by default)

Figure: Using Windows Explorer for your source control is a dream (great for designers too - who don't want to use VS.NET)

Suggestion to the TFS Team: I didn't see blame annotate in the drop down - which is a bit odd.

More reading from the prolific Brian Harry:
http://blogs.msdn.com/bharry/archive/2008/11/08/oct-08-tfs-power-tools-are-available.aspx
http://blogs.msdn.com/bharry/archive/2008/10/01/preview-of-the-next-tfs-power-tools-release.aspx

Do you need to migrate the history from VSS to TFS?

Suppose you are migrating from VSS to TFS, you need to consider if it's necessary to also migrate the history.

We suggest that you don't migrate the history, because:

• Normally, you don't need to check the history very often. If you do need sometimes, then get it from VSS.
• Save much space for TFS. For example, we have a about 7G VSS history database, and we may only need a small bit of them every 3 months, so what's the point of coping about 7G file when we only need one line of code?

But there are also some considerations that you may want to migrate the history:

• If the history of source changes will be checked very often, so you can check the old history with the recent together via TFS.
• You are going to decommission the old VSS completely. Say you don't want to keep the old VSS database, and then it will be necessary to keep the information somewhere.
• If the project is very active, then it will be worthy to migrate the history because your developers may need them every day.

If you are going to move the history, the links may help:

• http://msdn2.microsoft.com/en-us/library/ms181247.aspx
• http://blogs.msdn.com/buckh/archive/2004/06/10/152609.aspx
• http://blogger.xs4all.nl/tty1/archive/2006/04/09/85962.aspx

Do you know how to use branching?

Having a good branching strategy will save your bacon, or at least your code. Be careful when deviating from your branching strategy because if you do, you may be worse off than when you started!

Figure: Bad example, an unmitigated branch disaster

Figure: Good example, simple effective and supportable branching.

For more information see:
Guidance: A Branching strategy for Scrum Teams
Visual Studio TFS Branching Guide 2010

Do you know how to lay out your solution?

Creating a solution and having it maintainable over time is an art and not a science. We like being pedantic and having a place for everything, no matter how small.

Whenever we setup a new Team Project we implement a basic version control structure. We put "readme.txt" files in the folder structure explaining the different levels, and a solution file called "[Client].[Product].sln" located at "/[Client]/[Product]/DEV/Main" within version control.

Figure: Bad Example, how would anyone know how to sort this mess out?

Figure: Good Example, The ideal solution.

For more implementation details see:
http://blog.hinshelwood.com/archive/2010/05/17/guidance-how-to-layout-you-files-for-an-ideal-solution.aspx

Do you have a TFS Master?

The best way of getting the most out of TFS is to have a 'TFS master'. A 'TFS master' is like a Scrum Master but only interested in helping you get 100% from TFS:
• Taking you beyond, TFS as a source control system
• Getting TFS to help you on a proper ALM road
• Make sure that Build are created and managed properly by the developers
• Manage the Build servers (builds themselves are the responsibility of the developers)
• Check the builds are fit for purpose, and that unit tests are included
• Deployment is fine and working properly
• Checking Wix files
• Checking the right check-in policies are enabled
• Code analysis is enabled and getting stronger
• Code auditor is running
• Checking the reports are looking healthy
• Clean up unused Workspaces (this removes old check outs by default)
• Make sure all patches are applied to the servers
• Send out check-in warnings every week to people which have left over check outs. (No task should take longer than 8 hours)
• etc...

These duties need to be taken care of on a regular basis.

Do you know to always create a test if you are fixing a bug?

If you have been working to fix a bug always make sure that you write a test to make sure that the bug does not rear its ugly head again.
You can do this by Creating a Test Case and associating it with a test.

Figure: You can easily fix this by associating tests with a Test Case which in turn "Tests" a bug