Binding a Flare project to Subversion

[Nita Beck]

Question for those of you using Subversion for source control of Flare projects.

My client is considering having us use Subversion. We have several "local/child" Flare projects that import content from a "global/parent" Flare project. We want to source-control all the local projects as well as the global project.

If I use Flare's built-in feature to bind a local project to Subversion (rather than doing so outside of Flare, perhaps using the Tortoise plug-in to Subversion), will the items imported from the global project also be bound, rather than just the local items? That is not desirable. If that is how Flare will work, any suggestions for a workaround? If I bind a Flare project to Subversion outside of Flare, does Flare recognize that it's bound? Will I be able to use Flare's UI to check in, check out, and add to source control?

(For anyone interested, I had spent months investigating how to use Flare with ClearCase and had gotten fairly far down the road in the workflow. Then my clients, a software development department, for reasons having nothing to do with Flare, decided they would transition off of ClearCase over the next year. So my ClearCase research ends, and my Subversion research begins.)

TIA for any light shed...

[Nita Beck]

bumpity bump

[jcook]

What a coincidence... I too am investigating Flare 7 integration with the Subversion 1.6 version tracking tool!
Based only on some preliminary research (e.g., related forum postings and Flare 7 What's New videos):
1) Binding a Flare project physically adds the Flare project items to the Subversion repository (i.e., FSFS flat file data store). Flare folders/files then become versioned data within the Subversion tool.
2) Due to concurrency issues with Flare output files, when binding a Flare project, only the directories with the Flare source files should be present. For example, the Output and Analyzer directories should not be present when executing the bind operation.
3) Likewise, if you don't want to version control the imported items mentioned below, I believe that they should be removed before performing the bind to Subversion. (They'll be regenerated when you re-build the Flare project, correct?)
4) In subsequent Flare/Subversion operations, be mindful to not check-in (i.e., svn commit) into Subversion these output files or the imported files.

[Nita Beck]

jcook, this is indeed a coincidence. I'll admit to being a little dismayed not to have drummed up more ideas on the forums, but I am very grateful for yours!

Interesting idea to delete the imported items before binding to Subversion from within Flare. We'll need to be careful to tell Flare NOT to delete links, as we'll want those links present when we later reimport the global items. But I'm not yet convinced this will work. I want to know what Flare will then want to do with the reimported items. For instance, will it keep trying to prompt us to add all these items (which it thinks are new to the project) to source control? If Flare doesn't care, and if, as you suggest, we are careful not to commit the imported items to source control, perhaps that would be a fine workflow. (And we'd never want to bind Analyzer or Output to source control, or the Project/User folder either.)

Playing devil's advocate, I wonder if there is any harm in binding a child project WITH its imported global items to Subversion? Our workflow processes will dictate that the global items will only ever be maintained in the global project, so that should protect us from a Flare user's updating an imported global item in a child project. Perhaps the overhead of all those items bound to source control in the multiple child projects just isn't that big a deal. (But this might be my relative inexperience with source control speaking.)

Questions questions...

[Andrew]

Okay, I typed out a huuuuge response to this, but I reread it and realized it wasn't all that helpful, and consisted of at least 50% of me bitching about the terminology choices they (failed to) make for SVN integration. So, starting over!

If I use Flare's built-in feature to bind a local project to Subversion (rather than doing so outside of Flare, perhaps using the Tortoise plug-in to Subversion), will the items imported from the global project also be bound, rather than just the local items? That is not desirable.

I assume (but am not sure) they would be bound to source control. I'm confused as to why that is not desirable -- is it a space consideration?

If I bind a Flare project to Subversion outside of Flare, does Flare recognize that it's bound? Will I be able to use Flare's UI to check in, check out, and add to source control?

It will have no idea. You have to manually bind the project (and I would *not* suggest binding a project that has already been bound without doing some testing -- you might get some very strange issues, depending on how smart Flare is about the hidden SVN folders that control the local copy's link to SVN, history, etc.). I've used TortoiseSVN with Flare for a couple of years (with no integration; I use Tortoise to manage all the commits, updates, and conflicts, and use Flare to simply do authoring as if there was no source control at all). You will *not* be able to use Flare's checkin/checkout interfaces to do anything without binding the project.

Suggestions for GPL Strategies
For integrated projects, I don't know how Flare handles GPL. I would *hope* (but doubt) that Flare is smart enough to check the project settings of the parent project for its source control settings, and then, if it uses SC, get the latest versions of the linked files from source control. That would be the ideal -- you then don't have to do anything at all -- it "just works." I don't have an easy way to test this at the moment (I blew away all my 7.0 beta test projects from my SVN repository), but it seems like a *relatively* easy test: simply create copies of your two projects (the parent and child), add them to a test area of your SVN repo, and change the parent, then build the child.

If it isn't that smart about things, you'd have to do basically what I suggest in the following paragraph, but instead of a simple right-click option to update your parent projects, you'd have to open each one in Flare and update it. Yuck.

For non-integrated projects, using simply TortoiseSVN, GPL is not too hard (day-to-day; there is some setup). You can create a "subfolder" in SVN for all parent projects, then add all your parent projects to it. Add your child projects to SVN as normal. Create a location on your local drive that will *always* be used (on every PC that will access these projects), such as c:\svn\parents\. Use that folder as the local copy storage folder for the parent project subfolder you created in the SVN repository. In the child projects, set your GPL to the local folder (that's why you have to have the same folder for every machine -- the child project needs to always look in the same place). Before you build any project that links to a parent project using GPL, run an SVN Update on that one folder (basically, right-click the folder and select "SVN Update" from the context menu -- drop-dead easy), and all parent projects will be updated from SVN immediately.

BTW, if you do decide to use TortoiseSVN, make sure you understand which folders you want to exclude from source control (that's one of the benefits of Flare's integration: it does this for you): you probably don't want your Output, Analyzer, or Project\Users folders (and maybe a few others, like Project\Reports) to be included in source control. You'll have to tell TortoiseSVN to ignore them.

Hope that helps, and good luck!

[Nita Beck]

Thanks, Andrew, for the very long reply. I will digest it thoroughly tomorrow when I'm back at my client's site.

I have a great deal of experience with global project linking, so I do understand about needing each local project to look for the global project in the same location on each Flare user's machine. (Doesn't hurt, though, to spell that out for anyone following this thread!)

I've also got a fair bit of experience now using Flare with ClearCase, so I understand already that one doesn't want to put the Analyzer, Output, or Project/User folders into source control. (Likewise doesn't hurt to spell that out for anyone following this thread.)

My concern is that I'd like some control (no pun intended) about exactly what Flare binds to Subversion. I don't want it to bind any of the stuff that is imported from the global project. It seems inherently messy to me that we could be in a situation in which we had the "real" global project in source control and then 8, 9, 10 "imported" global projects (well, not the project of course, but lots of stuff from it) also in source control within the local projects to which they have been imported. It's not merely a space issue. It's that I want all the Flare authors to have a very clear understanding of where anything imported from global needs to be maintained, i.e., back in the "real" global project.

Furthermore, we will have situations in which some local projects will import from multiple other Flare projects (e.g., the global project and another local project). For those projects, I want to bind to source control only the items that are maintained locally within those projects.

jcook had an interesting idea that I'm going to test out once my client gets a Subversion repository in place, the idea of first binding a local project before anything else has been imported to it.

And your idea about whether Flare is "smart enough" to know when imported items are bound to source control. That'll be another experiment to try.

If Flare isn't "smart enough" to give me the control I think we need, then I will explore using the TortoiseSVN plug-in, though that would lose us the convenience of being able to check in, check out, add, etc. from within Flare.

Let me say again, Andrew, THANK YOU for replying. I very very very very much appreciate it. Would you be open to my sending you an occasional PM?

[Andrew]

Regarding including / excluding GPL'd content: didn't mean to suggest you shouldn't want to exclude that; I didn't understand it so I asked. It seems much messier (to me; if you disagree, it hardly matters what I think, since it's not me managing the projects. ) to try to pick and choose the stuff from the project that goes into source control, because Flare is going to add it all to its list of "pending adds," and it will sit in that list until you add it (you can check in and simply deselect it from the checkin dialog, but it will remain in the pending checkin list). Flare's Subversion integration does not (to my knowledge) offer the ability to exclude files from source control. If it's in your project, Flare wants to commit it. Every time you commit your entire project, or look at the pending checkins list, you will see these files (and someone, at some point, is bound to make a mistake and commit something that was supposed to remain uncommitted).

I took a look at SVN integration + GPL: Flare *does* include GPL'd files from the parent project in source control for the child project. Also, as we suspected, Flare does *not* bother to check the repo for the latest version of an imported file; it only looks at the physical location of the project it has been directly linked to. Yuck.

I don't know enough about SVN repo structure for this, but it may be possible to link directly to the repo (or to where the repo is stored) so you always get the latest version. I'm not very sanguine, but it might be worth taking a look if you have the resources.

Sorry about all the "newbie" stuff I put in there -- I wasn't really considering my audience (you'd think, as a tech writer, I would remember that ). I was thinking back to when I first tried to figure all this out on my own, and remembered some of the gotchas I ran into, so I stuck 'em in. At least they might help some other poor soul reading this.

Feel free to PM me anytime.

[Judith]

I've been using Flare with subversion for a couple of years and have been using Tortoise to import and export projects, and check working copies in and out. In Tortoise, the "external items" feature allows you to construct a working copy from a number of different checkouts. So you can hold your master project just once and link it as an external item whenever you check out a working copy of a Flare project.

I haven't tried this myself, but I'm about to start testing. Wish me luck!

Nita - I don't pretend to be a Tortoise expert, but all our developers use it so we have a lot of experience between us. Let me know if you think we can help.


Judith

[Nita Beck]

Thanks very much for your reply re Tortoise, Judith. I really appreciate it. And good luck with your experiments!

That said, we don't want to use Tortoise. We are eager to use Flare V7's native integration with Subversion, and my question revolves around that model. We'll look at Tortoise only if there is no other way to get Flare to play the way we'd like it to.

[TechnicalDisaster]

Nita,
I've been using Flare for the last two years inside of subversion with global project linking my child projects to my master project. I've only started to use Flare's subversion integration and have used Tortoise SVN since the beginning. This is just my advice, take it or leave it, but you are adding a lot of complexity and overhead by keeping linked files out of SVN in your child projects - for a reason that isn't completely clear to me. If a file has been imported into a Flare project and linked to a master file, subversion does not change Flare's behavior. You will still see your linked topics with a link icon when they are comitted to SVN, Flare still keeps them linked, and the only thing that changes is those files are copied to the SVN server with all the rest.

I'm not sure how you are looking at archiving your work, but not keeping all your linked files in SVN is going to be a huge problem if you have to restore a previous work. You will only be able to restore what was commited to SVN, so if you need to republish a previous version and you don't have the master files in the project, you will only be able to restore a partial project and have to manually replace anything that is missing. Subversion has some great export tools to make local copies of projects that I use as my 'playground' on my desktop for when I need to make changes and enhancements to the projects. If my master files were not checked in to SVN, I would have to create a local copy, and then re-import all my master files again. I'm trying to understand the merit to keep them separate, but I just don't see it.

That being said, you can set up Subversion to ignore files that are added and committed based on their extension. That will keep out a lot of the files synced between the master and child projects, but not all. It's an all or nothing set up, so if you have htm files coming from your master project you shouldn't exclude those from subversion, or else you won't be able to commit any of your topics. Also, Flare subversion integration HATES when you make files ignored on the Subversion side and tries to add and commit everything regardless - so going that direction requires you to use something like Tortoise or else you'll get error messages evey time you add and commit through Flare.

Maybe you can make an enhancement request to have Flare allow you to create an ignore list for source control. Just like you can set your import files to ignore certain files from your master project, we could have the ability to ignore specified files for source control as well.

[Nita Beck]

@ TechnicalDisaster: Ding, ding, ding, ding, ding!

The lightbulb over my head has lit up, thanks to you. You've given me a clear understanding of the MERITS of binding not only the local items but the imported items to Subversion, specifically as insurance in the event we need to reproduce a given version of a local project as it existed at a specific point in time.

One question: You write "If my master files were not checked in to SVN, I would have to create a local copy, and then re-import all my master files again."

Won't I always need to have a local copy of the global project anyway? I have my local projects set up to auto-reimport at (target) generation, to ensure that every build always includes the latest stuff from the global project. Do you not use that feature?

[TechnicalDisaster]

One question: You write "If my master files were not checked in to SVN, I would have to create a local copy, and then re-import all my master files again."

Won't I always need to have a local copy of the global project anyway? I have my local projects set up to auto-reimport at (target) generation, to ensure that every build always includes the latest stuff from the global project. Do you not use that feature?

Sorry I didn't mean to muddy the waters here.

Yes, you will always have a local copy of the global project. For some reason I had it in my head that the global project was using relative links to the child projects, but a quick check of the import file shows it is an absolute link. My scenario was exporting a copy out of SVN to a new location, that would have broken the links had they been relative.

You may need to train your writing staff to take updates on the Global project in SVN before they build. It will auto-reimport from the Global project, but if the user has not updated their local copy of the global project they won't be taking any updates at all. (I don't know what kind of experience they have using source control).

There are times when you will want to play with your projects and not be hindered by source control, so you can export a clean copy out of SVN to a new destination (I usually use my desktop) and do your work. This is especially true if you need to start renaming folders or do project wide find & replace in html.

We created a guide for our team using Flare and SVN. I haven't looked at it in awhile, but it might contain some tips and gotchas that we stumbled over. Of course, it is using Flare/SVN/Tortoise.

[Nita Beck]

Thanks for confirming that, yes, we'll always need a local copy of the global project.

You may need to train your writing staff to take updates on the Global project in SVN before they build. It will auto-reimport from the Global project, but if the user has not updated their local copy of the global project they won't be taking any updates at all. (I don't know what kind of experience they have using source control).

Yes, part of my recommended workflow will be always to first update the local copy of the global project from Subversion. Next, in the local project (after also updating it from Subversion if needed), manually re-import the global items. At that point, the local project is ready to be worked on. Does that sound right?

One of the authors has a lot of experience with a source code control, although with a different tool; but he's relatively new to Flare. The other author is also new to Flare as well as new to source code control. My role is to figure out the workflows and then train them.

We created a guide for our team using Flare and SVN. I haven't looked at it in awhile, but it might contain some tips and gotchas that we stumbled over. Of course, it is using Flare/SVN/Tortoise.

That's precisely what I'll be doing. I've already written a doc that covers how to maintain the Flare projects; I'll be adding material to it on how to source code control the projects. Hey, if you want to share the love and let me peek at your guide, that would be great! (I realize you probably can't, that it's probably proprietary to your company.)

[TechnicalDisaster]

Yes, part of my recommended workflow will be always to first update the local copy of the global project from Subversion. Next, in the local project (after also updating it from Subversion if needed), manually re-import the global items. At that point, the local project is ready to be worked on. Does that sound right?

Yes. Be sure to add and commit your child project after you have re-imported from the master project.

[Paul Griffiths]

I'm interested in implementing the sort of GPL linking that Nita describes, using Flare's SVN support.

When you manually re-import globally-linked files into the child project, does Flare recognize that as a change to those files and automatically check them out of SVN in the child project (i.e. exactly as if the author had edited them)? Is the behavior the same for auto-reimport?

[Nita Beck]

When you manually re-import globally-linked files into the child project, does Flare recognize that as a change to those files and automatically check them out of SVN in the child project (i.e. exactly as if the author had edited them)?

Yes.

Is the behavior the same for auto-reimport?

I'm not sure without testing but I fully expect yes.