Best practices for source control and branching in TFS

This forum is for all Flare issues related to using Source Control.
Post Reply
BlueSkyM
Jr. Propeller Head
Posts: 5
Joined: Tue May 20, 2014 4:54 pm

Best practices for source control and branching in TFS

Post by BlueSkyM »

Hello,

We use TFS for source control of our Flare content, and I am looking at using the "development, main, and release" (https://www.visualstudio.com/en-us/docs ... ategically) branches in the same way as our developers.
We already have de facto main and release branches, but I do have concerns that we are branching content unnecessarily. The branches would be used much the same as with the developers.
Our help is a merged project of several large Flare projects.

Just to clarify my understanding of how each branch would work:
  • Dev branch: This would control help content that is experimental or not reviewed by QA. I am considering adding this extra type of branch for projects that are undergoing a lot of change. These changes can make it hard for me to isolate stable content for translation.
  • Main branch: This contains content that is stable, reviewed by QA.
  • Release branches: A separate branch of the help that we need to update going forward. We need these in a small portion of our help. Related my comment for the Dev branch, I hope that the release branch would be a stable and self-contained chunk of content for translation.
Does anyone have any experience that they can share that uses this type of branching or a mix of different types of branching for a merged Flare project?

My situation is a bit more complicated by the presence of shared snippets between the Flare projects. I've experimented with Global Project Linking with some promising results but I'm not sure how the versioning would work for these shared snippets.

Most importantly, does anyone know of any reference books or sites that have best practices for branching and source control for software documentation? I've looked but all I've really been able to find a few sites that talk about git and not TFS. Conceptually I understand that they are very similar, but I would really appreciate any additional sources (especially related to TFS) to point to when making the case to make these changes to my boss.

Thanks,

Mark
Wendy_Pod
Propeller Head
Posts: 21
Joined: Thu Jun 15, 2017 2:50 pm

Re: Best practices for source control and branching in TFS

Post by Wendy_Pod »

Hi Mark - wondering how you made out with your branching investigation?

We are currently planning our TFS implementation and are trying to determine best practices for organizing content. We haven't implemented global project linking as yet, but would like to be able to do so with a minimum of angst in the future.

Any wisdom you would be willing to share would be very much appreciated.

Wendy
AlexFox
Sr. Propeller Head
Posts: 149
Joined: Thu Oct 19, 2017 1:56 am

Re: Best practices for source control and branching in TFS

Post by AlexFox »

Hi Wendy,

I use TFS for source control for a team of two authors. My current setup works well so it's worth sharing. First and foremost I don't use any branching whatsoever. I don't see that it offers any benefits for authoring and using it just because developers do seems a little odd to me. I currently maintain 3 projects, one for the two distinct sides of my company (lets call them Product A and Product B) and one as a Master Project. They are all bound to the same TFS project, simply called Documentation. The two working projects are used as normal, each author adds them to Flare on their local machine and maintains a local workspace, checking in and out as necessary.

The Master Project sits on a network drive, and both authors work in this workspace (but not at the same time). It uses a conditional tag set (Settings_Project_Linking) and this has 3 tags defined, All, Product A and Product B. I tag the files I want to sync to the working project in the master project (css, js, pagelayouts, masterpages etc.) and each time I run the working projects I run an Import against the master project set to import all files, tagged with the relevant Settings_Project_Linking conditions.

The key points to be aware of are;
When adding the Master Project to Flare, add it by absolute network path, don't use a mapped drive letter. i.e. use \\machinename\yourarea\masterproject\master.flprj and not P:\yourarea\masterproject\master.flprj
Remember to run an import each time you open a working project, if changes have been made to master
Don't edit linked master files in the working projects (Flare will warn you about this anyway)

This approach will scale to any number of working projects and the use of the Master Projects ensures that all of your key files are always consistent and up to date.
Wendy_Pod
Propeller Head
Posts: 21
Joined: Thu Jun 15, 2017 2:50 pm

Re: Best practices for source control and branching in TFS

Post by Wendy_Pod »

Hi Mark/BlueSkyM.

Thanks so much for your reply. After some reading, I agree that branching seems to hold little benefit to most authoring setups, with the possible exception of a large project being co-authored concurrently. Not a workflow that our team plans on adopting.

I love the tagging idea for import - I can see that working well for our team as we are supporting a large catalog of products and their associated documentation. Tagging would help us apply some logic when importing template and other content updates.

Regarding the project linking, I found an interesting thread (viewtopic.php?f=68&t=28194) were David Lee has a promising workaround to the multiple file paths issue...
We have projects in TFS that use imports, and had a similar problem with the import file path name.

To get round the problem, we did this:

(1) Get the projects from TFS, and make sure that they're in the same parent 'projects' folder;
e.g. the parent is C:\Users\bob\Documents\projects\, so your projects might be
C:\Users\bob\Documents\projects\StyleGuide\StyleGuide.flprj and
C:\Users\bob\Documents\projects\AnotherProject\AnotherProject.flprj

(2) Set up a drive mapping for the parent 'projects' folder; e.g. set drive 'P:' to C:\Users\bob\Documents\projects\
I use the prompt 'subst' command for this:
CODE: SELECT ALL
subst P: "C:\Users\bob\Documents\projects\"


Everyone else maps a drive using the same drive letter 'P' to their own projects folder, e.g. C:\Users\jane\Documents\projects\ or F:\MyWork\projects\
We create a batch (*.bat) file with the 'subst' script above, and run it on Windows startup so it's always ready.


(3) When you set up an import, select the project from drive 'P', e.g. so the path is something like P:\StyleGuide\StyleGuide.flprj

This means that the path to the project (from P:) is the same on everyone's PC.
Boone
Propeller Head
Posts: 44
Joined: Thu Jan 31, 2008 10:24 am

Re: Best practices for source control and branching in TFS

Post by Boone »

I was considering using branching to save off released versions of content for a Flare project. For example, when Version 1 of Product 1 documentation is released, I would make a branch of this version in case I ever need to retrieve Version 1 sources. I also considered using labels (created in Visual Studio) to mark a specific version of the content.

My understanding is that there is no way to create a branch, or retrieve a branch, through the Flare TFS source control interface: Visual Studio would have to be used for both operations. Same is true if I used labels instead of branches: there is no way to create labels, or retrieve a labelled set of sources, through the Flare TFS source control interface. Is my understanding correct?

Is there a better way that MadCap recommends to mark and retrieve a specific version of content?
Post Reply