The end of Version Control Guidance? A pinch of nostalgia and future plans.


A bit of nostalgia

The Version Control Guidance adventure was the first project I engaged with the ALM Rangers, then known as the VSTS Rangers, working on the TFS Branching Guide. It has grown into a blockbuster that not only shared insightful and practical guidance around branching, merging and other source control concepts, but inspired our German, Spanish and Japanese communities to localise the guidance over 9 years.

image image
Extracts from the Japanese edition in 2010.

Releases

The download stats on CodePlex from January 2010 show healthy growth, sustained support and spikes of excitement, especially when we introduced the crisper format.
image

2010 1.0
1.0.1
1.0.2
1.0.3
Upgrade and retired TFS Branching and Merging Guide. The Version Control Guidance is born.
Japanese localized edition.
German localized edition.
Spanish localized edition.
2012 2.0 Visual Studio 2012 focused guidance.
2014 3.0
3.0.1
Introduction of a crisper style and focused on Strategies, TFVC Gems and NuGet guidance.
Spanish localised edition.
2015 3.1
3.2
Revision of Strategies, TFVC Gems and NuGet guidance.
Introduction of the fourth guide Git for the TFVC User, complemented by the
Git for the TFVC User call for feedback blog series.

Future

Nothing describes the future of the Version Control Guidance better than the infamous quote from Winston Churchill: “Now this is not the end. It is not even the beginning of the end. But it is, perhaps, the end of the beginning.”

Two of our strategies influencing the next Version Control Guidance are:

  • Simplicity … practical, crisp guidance, reducing waste and increasing user value.
  • Openness … open source and allow community contributions.

We are not planning a revision of the Version Control Guidance on CodePlex, moving the solution from active to service mode on our Library of tooling and guidance solutions (aka.ms/vsarsolutions) page.

Instead we have been collaborating with Matt Mitrik and his team, exploring a three-pronged strategy:

  1. Mainstream Documentation – Deliver crisp, markdown based, guidance which is “merged” (excuse the pun) with the new Version Control documentation on …vs/alm/Code/overview. You will be able to peruse the professional product documentation and practical guidance “as one”, in a discoverable and consistent style.
  2. Out-of-Band BLOG Series – Deliver dogfooding, research and from-the-field experiences on our …/visualstudioalmrangers/ blog. We will continue to share our experiences and explore concepts that may migrate to the mainstream documentation over time.
  3. OSS – Continue investigating the Git-based Pull Request concept on Visual Studio Online and GitHub, to enable the ALM Community to contribute to the guidance.

We need your help!

Which sections of the Strategies, TFVC Gems, NuGet and Git for TFVC User guides do you want us to retain, maintain, enhance and what you see as mainstream or out-of-band?

Please add your candid thoughts below of ping us on email.

Comments (3)

  1. Josh Garverick says:

    I believe the Git for TFVC User guide is really useful because there is still a need in the community to understand the differences for those who are interested in making the switch.  I also think the Strategies guide is valuable as there will always be folks who have a need to find that strategy that will take them to the next level.  

    Both Git and TFVC would be mainstream IMO.  For OOB, I'd suggest other source control providers and how there may be support for them at some point using the Xplat agent and/or Windows vNext agent.  I'd suggest SVN to start with, unless there are compelling cases for other SCMs.

  2. Anonymous says:

    I think the direction we're going is a great one. Merging with the 'official' documentation and offering one place where users can find all the details they need sounds like a good idea.

    I would love to see the Open Source model become a reality. Having the overall community be able to contribute to the guidance will be a huge win.

    When it comes to choosing where our content should be delivered I have the following ideas:

    – The strategy sections are the core of the guidance. I would love to have these merged with the official documentation

    – The Gems sections looks likes something that could be delivered out of band.

    – NuGet and Git for TFVC could be part of the main guidance.

    I would use the out of band blogs to deliver 'extra content' like best practices, tips and quick updates.

  3. Anonymous says:

    I think there are lingering needs now about how various branching and version control strategies can support rapid release/DevOps movement.

    I can also see a need for next level stuff in deeper formats for things like feature toggling.

    Also guidance around doing things with Azure PaaS in terms of version control… for example like deployment techniques for cloud service packaging.

    Everything should be crispy and light of course.

Skip to main content