Skip Navigation LinksHome > SSW Standards > Rules > SSW Rules to Better Source Control with TFS

You should always use a source control system! SSW uses and recommends Microsoft Team Foundation Server (TFS) using Git for source control. Source control allows the tracking of changes to code as well as a backup of your source code. This is also very useful when debugging and fixing errors as you can locate changes that have been introduced and see the lines that were updated.

Do you agree with them all? Are we missing some? Let us know what you think.

Red star Indicates important rule


  1. Do you know the benefits of using source control?

    The standard answer to this question is that it allows team development and provides a backup of all of your code and changes.

    The best answer is that it lets us find exactly what changed to break the application, and who did it. A lot of the time you spend as a developer is fixing bugs. You don’t want to just keep making changes, you also want to inform the person who made the error.

    In Team Foundation Server, you can see who made a change that introduced an error and let them know.

    source-control-benefits
    Figure: OK Example – You can view the changes for an individual file or folder
    source-control-benefits
    Figure: OK Example – we can select different changesets and compare the changes
    source-control-benefits
    Figure: OK Example – we can select different changesets and compare the changes. Green = added, Red = deleted
    source-control-benefits
    Figure: Good Example – right-clicking on a file and selecting Annotate lets you view the person last worked on the file and should be CCed when bugs are discovered in his code
    source-control-benefits
    Figure: Good Example – using annotate allows us to find the coder who made specific changes, to understand their thoughts before deleting/changing their code
    source-control-benefits
    Figure: Good Example – clicking on the changeset Id shows us all the files that got checked in at that time as well as their comments
  2. Do you know the right source control to use?Red star

    SSW uses and recommends Team Foundation Server, using Git as the source control option.

    Team Foundation Server has some great features that make it a great option for teams serious about producing great software.

    Integration with a complete set of application lifecycle management tools

    Team Foundation Server isn’t just source control, it also gives you the tools to manage your complete application lifecycle. From awesome agile collaboration tools and work items for tracking requirements, to managing and running manual and automated test suites, through to build and deployment services and tools, TFS gives you a fully-integrated platform to develop great solutions from end to end.

    For more information on effective project management with Team Foundation Server, see the Rules to Better Scrum using TFS.

    Visual Studio integration

    TFS integrates with Visual Studio incredibly well. Most of the features are surfaced in the IDE so you never have to switch programs.

    You can even integrate TFS with Eclipse or just use it from Windows Explorer or the command line!

    Multiple options for source control

    Team Foundation Server 2013 lets you use either a centralized source control system (Team Foundation Version Control ) or a distributed source control system (Git) for managing your code.

    There are reasons for using both and it depends on your development team and what the workflow they’re comfortable with. Both are good options, but at SSW we use Git for new projects because it helps us make multiple small commits before pushing big changes to the server. To find out when you should use Git, see Do you know when to use Git for version control?

    Multiple options for hosting

    Team Foundation Server is available both as an on-premises product as well as a cloud-hosted system through Visual Studio Online. You can get full control by installing it on your own servers, or you can let Microsoft do the work and host it for you at visualstudio.com.

  3. Do you make small changes and check in early and often? Red star

    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. What happens if someone has to take over from you?
    Check-In Regularly
    Figure: Bad Example – don't try to eat too much at once

    We recommend a check-in:

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

    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: Git makes it easier for developers to work in small chunks. It encourages frequent local commits before pushing a bunch of changes to the server at once.

    Exception: What if you’re doing a large refactor?

    You should always write software using an architecture like the Onion Architecture that allow small checkins that won’t break the build. However, despite your best efforts, you might find yourself with a large refactoring job on some legacy code.

    Git logo

    If you're using Git, you have two options for saving unfinished work:

    1. Create a "backup" branch on the server and push your changes there
    2. Use local commits and make sure your hard drive is backed up daily (preferred)
    TFS logo

    If you're using Team Foundation Version Control, you can use Shelvesets or the My Work feature to save your unfinished work to the server.

    My Work lets you suspend your work to save your changes (it uses a Shelveset in the background), and makes it easy to resume your work later. It will even restore Visual Studio to the state it was when you suspended, letting you pick up exactly where you left off!

    source-control-checkin
    Figure: OK Example – click Shelve to save your changes without checking in
    source-control-checkin
    Figure: Good Example – use Suspend in the My Work hub to save your unfinished changes
  4. Do you enforce comments with check-ins?Red star

    Developers should always add a comment to every check-in they create. This lets the other developers know what was changed and why. Without comments, some of the great built in TFS features like History become far less useful.

    comments-checkin
    Figure: Bad Example - no comments against the check-ins mean we don't know what changes were made in each revision
    comments-checkin
    Figure: Good Example: Now we can pin point which revision a particular change has been made
    Git logo

    If you're using Git, you can't enforce this rule out of the box!

    TFS logo

    If you're using Team Foundation Version Control, you can enforce this behaviour.

    To enforce this behaviour, you will need to:

    1. In Team Explorer, go to Settings and click Source Control in the Team Project section
      comments-checkin
    2. Select the Check-in Policy tab
    3. Click Add
    4. Select the Changeset Comments Policy
      comments-checkin

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

  5. Check-in – Do you enforce work item association with check-in? Red star

    One of the big advantages 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 requirements are the spirit. Work Item association helps us to link the spirit and body of software together. This is especially useful when you're trying to identify the impact of a bug in terms of user requirements.

    Git logo

    In Git, you can associate your changes with a work item using the comments field.

    source-control-checkin-enforce
    Figure: You can reference work items directly in your commit message
    TFS logo

    If you're using Team Foundation Version Control, you should associate a work item when you check in.

    source-control-checkin-enforce
    Figure: Bad Example - no work item is associated with this changeset
    source-control-checkin-enforce
    Figure: Good Example - a work item is associated with this changeset

    In order to achieve this, developers need to use the Related Work Items to add a work item by Id or by query.

    Even better, developers should associate their changes to a work item using the My Work feature before they start developing.

    source-control-checkin-enforce
    Figure: OK Example – associating a Work Item with the Changeset
    source-control-checkin-enforce
    Figure: Good Example – associating a work item using the My Work feature
    Git logo

    Git doesn't support checkin policies, so you can’t enforce this rule out of the box.

    TFS logo

    If you're using Team Foundation Version Control, you can take it one step further and enable the "Work Item Check-in Policy" to enforce this rule in your team.

    To do this, you'll need to install the Team Foundation Server Power Tools, then enable the Work Items check-in policy.

    source-control-checkin-enforce
    Figure: Always enable the "Work Items check-in policy"
  6. Do you know how to structure your version numbers?

    Version numbering for .Net assemblies should take the structure: [Major].[Minor].[Revision].[Build].

    • Major – should only change with major upgrades or a new platform (e.g. Windows 8).
      For projects that have not yet been released to production, this number should be 0 and should only change to 1 on the first release
    • Minor – for new features and releases that are customer facing, ideally incremented every sprint
    • Revision – for emergency maintenance or security patches to the customer
    • Build - internal build number to differentiate different builds. It should not be incremented manually

    This strategy fits very well with the Release Branching strategy we recommend in our Rules to Better Branching and Builds. Whenever a patch needs to be applied to a version of an application, you can branch off the released version, apply the changes, and release a new revision. Finally, you can merge your fix back into the trunk.

    source-control-version-numbers.jpg
    Figure: Example process where a patch needs to be applied to 1.1.0 in production
  7. Do you work on one task at a time (aka. Do you check-in all files?) Red star

    You should always try to limit your work to one task at a time so that your check-ins can be tied to a single piece of work. If you stick to this rule, you should always be able to check in every modified file at the completion of a task.

    If you're working on a few tasks without doing a check-in between them, you can find yourself only wanting to check in a few files rather than everything. This can lead 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, and you don't want to break the build! So either, check-in all the files you are working on or none at all if you aren't finished working on the task.

    The best way to manage the tasks you're working on is to use the My Work hub in Visual Studio. See the "Do you use the My Work hub?" rule for more information.

  8. Do you always allow multiple check-outs? Red star

    In the past, source control systems like Visual SourceSafe were not good at merging. Developers also tried to avoid having to merge files, because it was too hard. Team Foundation Server lets you only allow one person at a time to check out a file, so there will be no chance of a conflict that needs merging. However, you should always allow multiple people to modify a file at the same time!

    There are two reasons:

    1. These days, a developer will rarely be working on a single file at a time. If they check out file A, then later go to work on file B to complete the change only to find another developer has it checked out, they're stuck!
    2. Usually, team members will be working on different files or different sections of the same file. You'll lose productivity if developers can’t work on the files they need to even if the changes don't affect the rest of the team. Merging tools are very good these days and can usually resolve conflicts that don't involve the same section of code.
    Check-out settings for files
    Figure: Enable multiple check-out should always be checked
  9. 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

    Source Safe VS.NET
    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.

    Source Safe VS.NET
    Figure: Use TFS Sidekicks to undo old checkouts by selecting them and clicking "Undo"
  10. 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, .html and .cshtml files. However, there is a lot more to your project than just source code. You should include all relevant non-compiled files in source control to avoid the following:

    • losing work
    • losing old versions of work
    • having 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
    • All source code and markup including HTML, CSS, and JavaScript files
    • HTML files
    • Image files 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 (these take up too much room)
    • Compiled .dll and .exe files (you should exclude the bin and obj folders)
    • Installers eg. .msi
  11. Do you include original artwork in Source Control?

    Your original digital artwork is an asset and 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. You may 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 artwork in your source control 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 choose 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.

  12. 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 or project and choose Source Control | Undo Pending Changes
      • Undo Pending changes
        Figure: You can undo pending changes right from the Solution Explorer
    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.
      • Find the revision before you started checking code in using the History command
        Revision List
        Figure: The last revision before Drew made changes was 63428
      • Right-click the changeset and choose Rollback Entire Changeset
        Rollback Changeset
        Figure: You can rollback to a changeset from the History window
  13. 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 solve 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.

    Rule to forward port 80 to the TFS port
    Figure: Rule to forward port 80 to the TFS port

    Tip: you should also consider exposing your TFS server via HTTPS and port 43. This provides extra security.

  14. Do you use the Windows Explorer Integration?

    1. Install the TFS Power Tools from aka.ms/TFS2013PowerTools
    Use Windows Explorer
    Figure: Using Windows Explorer for your source control is a dream (great for designers too - who don't want to use VS)
  15. Do you need to migrate the history from VSS (or another source control system) to TFS?

    Suppose you are migrating from VSS or another source control system 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 sometimes, then get it from the old system.
    • This will save a lot of space for TFS. For example, if you have a 7GB VSS history database, you probably only need to look at a small bit of information every 3 months, so what's the point of copying about 7GB of data when you only need one line of code?

    But there are also some considerations that may prompt you 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 worthwhile to migrate the history because your developers may need it every day.

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

  16. 1. Do you know to always create a test if you are fixing a bug (aka Red Green Refactor)?

    If you need to fix a bug, you should write a test first and follow the Red-green-refactor process. This will help you verify the fix and make sure it doesn’t happen again.

    The process is:

    1. Create a test for the broken code – the test should fail when run (Red)
    2. Update the broken code so it works correctly – the test should now pass (Green)
    3. Refactor the code if you need to improve its quality – the test should still pass so you can be confident you haven't broken anything (Refactor)

    If you find you can't write tests around the broken code, that's a sign your code is not structured very well. You should follow the Do You Use a Dependency Injection Centric Architecture rule.

  17. Do you know what type of TFS workspace to use?

    In most cases, you should use Git or Team Foundation Version Control with local workspaces in Team Foundation Server (we recommend Git) for source control.

    There are three reasons you might want to consider Server workspaces:

    You might consider using server workspaces when you have a very large codebase that you’re working on. Using a local workspace will keep a (compressed) copy of everything on your local machine so you can rollback any changes you make while you’re offline. If there are a very large number of files (more than 100,000) it may take a long time for the disk scanner to determine which files have changed. In some cases you may even get a timeout error.

    Use them when you are using checkout locks (not recommended). Because you’re not talking to the server when you start editing a file, your machine can’t enforce checkout locks.

    If you have some people working in VS 2010, local workspaces will be invisible to them.
    Introduced in TFS 2012, prior to then.

Acknowledgments

David Klein
Tristan Kurniawan
Ryan Tee
Justin King


Benefit from our knowledge and experience!

SSW is the industry leader in Custom Software Development, Software Auditing & Developer Training.

Call us on +61 2 9953 3000 or email us for a free consultation

What does it cost? I’m not in Australia. Can you still help?