Pretty basic SVN question

[mlaird]

Hey there!

My docs team is starting to use SVN for our Flare projects, and I have a question.

We've had success creating new projects and integrating them with SVN from within Flare, but we also have a number of projects that we created before we decided to use SVN, and I'm not sure about the best way to put these existing projects into source control. I'm sure there's an option to do this somewhere in the interface, but I haven't been able to find it. We tried adding things to SVN from outside of Flare (just using SVN directly), but we ran into some very weird behavior when we tried it that way.

Any advice on the best way to get this done?

Thanks!

[Nita Beck]

First make sure that you set up the folder structures in SVN to hold those existing projects. So, for example, you'll have a trunk folder for each project.

Then, for each project, do this:
1. Using TortoiseSVN to view the repository, navigate to and copy the URL to the project's trunk folder.
2. Open the project in Flare.
3. Open the project's Project Properties, and switch to the Source Control tab. There, click Bind. Then follow the wizard, and paste in the URL you copied into the applicable field.

Note that binding the project to SVN might take quite a while, depending on the size of the project. For my projects (which run into the 700+ file size), it might take half an hour or more. Just BE PATIENT and let Flare do its thing. It may appear to hang, but it's just doing a lot of stuff in the background. Then all of a sudden, you'll see all the filenames go flying by. When Flare's done, it'll close the progress window automatically.

And that should be it for each project.

From this point forward, I suggest that you only use Flare for day-to-day operations such as check-in, adds, renames, moves, etc. Use TortoiseSVN for the occasional operation, such as making a branch, merging a branch, viewing the repository, breaking locks, and so forth.

[techwriter31]

Hi Nita,

We're using ClearCase and are considering moving to SVN. Based on your post, it sounds like each project has its own repository. Is this correct? Or can you have multiple projects in a single repository?

Thanks!

[Nita Beck]

Kellie, there's a single repository (server), but there are separate folders. As a freelancer, I have one repository with folders for each of my clients who don't otherwise do source control. (I do it myself 'cause it's the smart thing to do.) Within a client folder, I have a folder for each product's documentation (i.e., Flare project). So it looks kind of like this:

SVN repository
--Client A
----Product 1
------branches
------tags
------trunk <<---- this is where the Flare project is bound
----Product 2
------branches
------tags
------trunk <<----- Flare project
--Client B
----Product 1
------and so forth...

For one of my clients that has their own SVN server, we've set up folders for each product. So it looks like this, with more than 25 product folders altogether (as well as one for a global project that holds common stuff):
--Product 1
----branches
----tags
----trunk <<---- Flare project
--Product 2
----branches
----tags
----trunk <<----- Flare project

Hope this helps.

[mlaird]

Thank you, Nita! That was exactly the information that I needed.

I was looking for a 'bind to source control' option in the source control tab, or in the 'file -> source control' menu, and it wasn't there. Now that I know where to look, the process is perfectly straightforward.

Much appreciated!

[techwriter31]

Yes, thanks Nita! I'm still getting used to terminology changes with SVN, and we haven't actually converted yet...

I believe our structure would be similar, but we'd have multiple Flare projects bound within the trunk.

SVN repository
----Product Line 1
------branches
------tags
------trunk
-----------Product Family A <<---- Flare project is bound
-----------Product Family B <<---- Flare project is bound
-----------Product Family C <<---- Flare project is bound
-----------Product Family D <<---- Flare project is bound
----Product Line 2
------branches
------tags
------trunk
-----------Product Family A <<---- Flare project is bound
-----------Product Family B <<---- Flare project is bound
-----------Product Family C <<---- Flare project is bound
-----------Product Family D <<---- Flare project is bound
----Product Line 3
------and so forth...

[Michael Cohen]

I find this entire Flare-SVN subject almost beyond my capacity to understand. My eyes have already glazed over three times reading this thread. What's a trunk? What's a tag? What's a working copy root? Source control should be AUTOMATIC, not trial and error.

In my case, we upgraded from Flare 8 to Flare 10, then discovered (by reading these forums and NOT any publication from Madcap; would have been nice to know going in), that we had to upgrade SVN to 1.8, which is on a separate server machine to which only IT has access. Then I still got errors about working copy roots (whatever they are), and the only way to connect to SVN from my Flare project (now opened in Flare 10) was to unbind it from SVN 1.8, thereby losing all of the history, then rebind the project in Flare 10 to SVN 1.8.

What am I doing wrong? I don't have time to spend half my life studying Subversion, I need to write documentation under strict and ever-changing deadlines.
How can this process be made easier and more automatic? Does ANYONE have a simple, step-by-step guide to doing this the right way that even a child could understand?

Thanks.

[Nita Beck]

Michael,

I'm sorry that you're having so much trouble with this subject, and I regret that I don't have the time right this minute to help answer some of your questions.

But I did want to say that your IT department does NOT need to upgrade the SVN server to 1.8.x. Flare 10, as an SVN 18.x CLIENT, can interact just fine with an SVN SERVER that is not at 1.8.x. No need to bother your IT guys and gals. But Flare 10 is different from Flare 8 in that it complies with the most recent SVN database structure, and that's why Flare 10 prompts you to update the source control database of the working copy of your project. What you can do is this: With Flare 10, import a FRESH copy of the project from Subversion. I can't tell you whether you need to import from the trunk, a branch, or a tag in the SVN repository.

Which brings me to SVN terminology. You really will have to invest some time in reading Subversion documentation. MadCap's obligation is only to document how their products interact with Subversion. (I do the same thing myself regarding Windows functionality; I tell my readers to read the Windows documentation, rather than documenting Windows functionality in the documentation for the software applications I write about.) Anyway, I suggest you check out the resources listed here: https://subversion.apache.org/docs/.

Also, there is a really nice overview of version control (aka source control), with focus on Subversion, here: http://betterexplained.com/articles/a-v ... n-control/

Without meaning to overwhelm you, I hope this info helps.

[Michael Cohen]

Thanks for the links. I will check them out when I have time.

Apparently, we were told by Flare that there's an import function in Flare 10 that's undocumented - Import Project - that nobody here saw because it's at the bottom of the File menu and you have to click the little down arrow to see it. It imports the current project from Source Control. We've tried that for other Flare 8 projects and were successful.

It's been a frustrating process but we'll get through it. Made even more frustrating by the fact that I quit smoking a week ago and I'm ready to kick small animals.

[Nita Beck]

I agree that, in Flare 10, the Import from Source Control feature got "pushed off the menu" when MadCap added more features to the File menu. But the import feature is most definitely documented:

http://webhelp.madcapsoftware.com/flare ... ontrol.htm

Again, I hope this helps. (And keep up the good no-smoking fight! )

[Jess77]

From reading this thread, it seems like you can have multiple Flare projects in one repository. Is that right?

I have been tasked with researching Flare's source control capabilities with SVN. Specifically, I need to know can Flare support multiple repositories (say, one per Flare user) or does Flare require that there be only one repository for all of Flare for all users.

From reading this thread, it sound like both. It sounds like you can have multiple repositories or multiple projects inside one repository. Do I have that right?

We are going to have two writers each with their own projects.

Writer 1
-Project A
--Sub-project 1
--Sub-project 2
--Sub-project 3

Writer 2
-Project B
--Sub-project 1
--Sub-project 2
--Sub-project 3

To make it easy on both of us, I think we should set up one repository with a folder for each of us and then have each writer sync Flare to her folder in the repository. Does Flare support that setup?

From reading this thread, it sounds like it does.

[Nita Beck]

Yes, you can have multiple Flare projects in one SVN repository.

Yes, Flare would support the repository structure you are envisioning.

That said, I would not use that repository structure. One of the reasons for putting a Flare project in source control is so that more than one author can maintain it.

For my clients, we have one giant Flare repository in SVN. Then we have a top-level folder for (typically) each product we create user documentation for. Within each of those folders we have the standard branches, tags, and trunk subfolders. The Flare projects themselves are bound to the trunk folders.

Any of my clients' authors and I can all acquire a working copy of anyone else's project, and in my opinion, that's as it should be. What if one of us wins the lottery and suddenly quits (or something else happens so we're no longer in the picture)? Someone else will need to have access to that author's work. And having folders according to authors' names will eventually becoming rather meaningless as folks retire, transfer to a different job, and so forth. Yet I think the names of products will outlive the names of authors, from the corporation's perspective.

My two cents, for what it's worth...

[Jess77]

Thanks, Nita. This is all a bit over my head. I'll have to sit down with my manager. He's asking me what I want and I don't really know how this works for source files. I have checked in and checked out via SVN for output files but have never integrated SVN with Flare.

[Nita Beck]

Earlier in this thread, I provided links to two sources of excellent information about Subversion. The second link is to an especially well written and illustrated overview to source control with emphasis on Subversion. That one especially will give you a good conceptual overview, as well as an introduction to Subversion terminology (e.g., tag, which is something completely different from a Flare file tag or condition tag).

[Jess77]

Thank you!
Those links are great.