SVN - Linking a project to other projects

[Greg]

I am testing using SVN and Flare 9.1.1 together.

How do I configure my projects to import from other projects also located on the SVN?

Thanks,

Greg

[Nita Beck]

You need to have local copies of the Flare project you want to import FROM and the Flare project you will import files INTO using the Global Project Linking feature.

[alexhenry]

How can I get the configuration? Can you please give me the link?

[Nita Beck]

How can I get the configuration? Can you please give me the link?

Give you the link to what? I don't understand what you are asking for.

[stealth94rt]

I just had an email conversation with Flare tech support regarding using SVN with Global Project Linking. They told me:

It is not recommended to use global project linking in conjunction with source control, this workflow can cause a lot of conflicts within source control because the local version of a particular writers child project will be pulling from a local version of the master project, if that master project is not checked in constantly there will be conflicts between the local version of the child project and version that is source controlled. Basically, the workflow becomes very difficult to manage and convoluted, especially with more than one writer working on a particular project.

So, I was a bit frustrated after reading that, as I thought this was part of Flare's design. However, I then found this form/thread and it sounds like others are doing that (using SVN + Global Project Linking). Please let me know how it's working (the good and the bad). Thanks.

[Spectre]

Hi,

I've had the same conversation with MadCap support. I was querying the workflow, where you are using Global Project Linking, with the Global project (the files you want to link to) in SVN.

You are correct, the user would need to open the local golbal project and get the latest version before being able to import it into another project.

However, another option may be a better solution. Users can also save the Global project in a network drive instead of storing it in a repository.

We would consider this as a feature request since it currently does not import projects from a repository.

At no point have I been advised not to use Global Project linking with source control.

Cheers.

[Spectre]

Sorry, just to make my previous post a little clearer:

When MC support says the following, they were responding to my suggestion that not being able to link to the Global project in SVN is a bug.

We would consider this as a feature request since it currently does not import projects from a repository.

Cheers

[NorthEast]

However, another option may be a better solution. Users can also save the Global project in a network drive instead of storing it in a repository.

I currently use this method - the 'global' project is on a network drive, and I use a project to import files to the local project(s).
All projects (including the 'global' one) are in source control (VSS).

However, I would note that the 'global' project isn't edited frequently, and only by a single person at a time.
I haven't tested out editing the network 'global' project by multiple users, but I'd expect that's not going to be a good idea due to access conflicts.

[Spectre]

Dave,

Can I clarify a couple of points with you, as I'm close to switching my Global project from being in SVN to being on a network drive. The structure and workflow would be as follows:

- The Global project (project with my CSS and all common files, such as common images, snippets and so on) would be stored on a network drive, not in SVN.

- Each Live Project would be in SVN, with local copies to work on.

- To start a new project I would create the project locally, bind to SVN, and import the common files from my networked Global Project. At that point, these common files are now globally linked, and Flare checks whether there have been any changes to them, according to the settings that you've set for this.

Have you encountered any issues with this workflow? When you're updating the Global common files, you're just working with the Global project on the network?

Cheers

[NorthEast]

Dave,

Can I clarify a couple of points with you, as I'm close to switching my Global project from being in SVN to being on a network drive. The structure and workflow would be as follows:

- The Global project (project with my CSS and all common files, such as common images, snippets and so on) would be stored on a network drive, not in SVN.

- Each Live Project would be in SVN, with local copies to work on.

- To start a new project I would create the project locally, bind to SVN, and import the common files from my networked Global Project. At that point, these common files are now globally linked, and Flare checks whether there have been any changes to them, according to the settings that you've set for this.

Have you encountered any issues with this workflow? When you're updating the Global common files, you're just working with the Global project on the network?

Cheers

Not exactly the same - my 'global' project (used for common CSS, images, page layouts) is stored on a network folder, but it is also in source control (VSS). Flare doesn't mind if the project in source control is on a network or local drive, and I can work with the project in just the same way.

When people start a new local project, they set up the project import to point to the 'global' project on the network drive, and import files as normal. You can bind the project before or after the import, it doesn't matter, Flare will handle checking-out of any files updated by the import.

I've not encountered any problems, but to date it has only been myself who edits the 'global' project on the network drive.
I don't really know what would happen if multiple users were editing the 'global project, and simultaneously tried to edit the same file.

[stealth94rt]

I have been doing some experimenting with this (storing the Global project in SVN).

-I'm only using it for common items (boilerplate topics, CSS, global variables, global conditions, common graphics, etc.).
- I'm the only one who touches the content in the Global project.
- I'm the only one who starts a new project, so I would handle the import and making sure all is working before binding it to SVN.
- In the Global project, I have an Import file (Flare_Master4.flimpfl) that defines all of the imported files and their locations.
- I have the Targets in the new projects set to "Automatically get latest version of all files before generating the target.", and Auto-Sync is unchecked (so it will sync all import files).

What I've found is that if there is a change to the Global project, you don't see that change until you build one of the outputs in the new project. To me, that's not a huge deal because I only have boilerplate items in the Global project and those don't change very often. (Ideally, it would be nice if there was a way to force a refresh of the imported content, but I haven't found a way to do that.)

I think the big challenges are:
1. Making sure all contributors know that they need to open the Global project from SVN, so there is a local copy of that on their hard drive.
2. Making sure all the contributors have the projects stored in the same folder structure.
3. Making sure all the contributors know they can't break the links to the imported files. In other words, if they happen to try to edit any imported content and see the Linked Document dialog box, that they click Cancel (so the link is not broken) and then contact me to make the change.

It would be nice if Flare had methods in place to enforce this, but I don't think that's the case. Perhaps that's why they say that the Global Project Linking with SVN workflow is "difficult to manage and convoluted" and don't recommend it.

[Spectre]

Stealth

I haven't done full testing yet, pending a decision on the approach to take. But your thoughts are similar to mine. Hopefully my common files will be pretty stable by the time I need to start creating more projects. There's just me and one other author, so communicating the workflow shouldn't be a problem. I'm reasonably comfortable with the challenges you've identified, but not with the suggestion from MadCap that the "workflow becomes very difficult to manage and convoluted...." I'm rechecking with MadCap.

Cheers.

[stealth94rt]

Please post Madcap's response to your questions. Perhaps I'm missing other issues that haven't surfaced from my limited (2 days) testing.

[Spectre]

Please post Madcap's response to your questions. Perhaps I'm missing other issues that haven't surfaced from my limited (2 days) testing.

Absolutely.

[Spectre]

Hi,

The reply from MadCap is as follows. The workflow I'm asking them is the one where the Global project is in SVN. No dire warnings about the workflow being difficult to manage and convoluted.

Flare handles everything locally. This workflow is valid but keep in mind, users will only need to get the latest in the Master if a change has been made.

I have submitted a Feature Request on your behalf (#82421) with our development team regarding the ability for the master project to get the latest version when importing from a child project and you will be notified via email if this feature becomes available in a future patch or release version.

Cheers

[stealth94rt]

Yes, I actually just got a call from tech support and they told me the same thing. (Apparently, there was some misunderstanding or miscommunication about how those features interacted.)

During the call, I asked if Flare would automatically get the latest version of the Global project from SVN if the "Automatically get latest version of all files before generating the target." is checked in the Target UI, and I was told that "yes, it would". (My limited testing showed it was doing this, but I wanted to verify that it was supposed to work that way.) However, it only does this if you're building through the Flare UI and not from the command line.

[Spectre]

That's good - good that the general "don't put the Global project in SVN" recommendation isn't true.

But I'm a bit confused about the following:

During the call, I asked if Flare would automatically get the latest version of the Global project from SVN if the "Automatically get latest version of all files before generating the target." is checked in the Target UI, and I was told that "yes, it would". (My limited testing showed it was doing this, but I wanted to verify that it was supposed to work that way.) However, it only does this if you're building through the Flare UI and not from the command line.

Flare (by that I mean the Live Project) isn't getting the latest version of the Global project from SVN is it? It's getting the latest version from your locally stored version of the Global project. And the workflow assumes that prior to generating output for the Live Project, you're syncing your local Global Project with SVN to pick up any changes that someone else might have made to the Global files.

[marvin mallari]

Hello folks,

There are several workflows to consider when utilizing Global Project Linking and Source Control.

Here are some things to consider:

Workflow A would consist of the Master project being imported from source control locally to the writers machines. Then imported to the child projects(All done locally). Since Master projects do not get changed often, it would be best to notify the team of the change and prompt them to update their local copy of the Master Project.

Workflow B uses the network drive and does not require a "get latest". When the Master project is updated, the child projects import the master stored in the network drive without any other steps.

Hope this answers some of your workflow questions.

[Nita Beck]

Workflow A would consist of the Master project being imported from source control locally to the writers machines. Then imported to the child projects(All done locally). Since Master projects do not get changed often, it would be best to notify the team of the change and prompt them to update their local copy of the Master Project.

Marvin's first workflow is the exact workflow that my client's teams and I use. The Global project is bound to SVN, and each author has a working copy of it (as in, local to his or her machine). If one of us needs to make a change to the Global project, he or she alerts the rest of the team to that fact, sometimes before making the change, in case anyone objects, and sometimes afterward, 'cause maybe all he or she did was fix a typo or add an index entry. The changes are checked into SVN, and then the rest of the team can get the latest updates out of SVN and then import those updated global items into our respective Flare projects, either automatically or on demand.

[NorthEast]

Actually, there is one issue that is worth noting when using project imports and source control, and has caught out folks here.

When you re-import files, Flare will indicate which files are newer in your global/master 'source' project (in green) and in your 'local' project (red).

However, don't assume that you only need to re-import files that are newer in source (green); as it's not actually a reliable way to compare the files.

I think this happens in this sort of scenario:

Day 1 - User A creates files in a master/global project - version 1.

Day 2- User B creates a brand new project, and uses a project import to get files from a master/global project (version 1). They then bind the project to source control.

Day 3 - User A updates files in the master/global project - now at version 2.

Day 4 - User C gets the project created by User B from source control, which still has version 1 of the master/global project files.

Now, when user C runs a 're-import' on the project import file, Flare presumably compares the date that the user's local files were created (Day 4), to the date that the files in the master/global were last modified (Day 3). Therefore, Flare will say that the local files (version 1) are 'newer' than the files in the global/master project (version 2). So whilst Flare says the local files are 'newer', the file from the global/master project is actually out-of date.

Anyway, this caused problems for us, so our standard procedure now is to re-import everything that is different - marked newer in source (green) and newer in the local project (red).

[Spectre]

I'm looking to implement Workflow A, as described above by marvin, and repeated below:

Workflow A would consist of the Master project being imported from source control locally to the writers machines. Then imported to the child projects(All done locally). Since Master projects do not get changed often, it would be best to notify the team of the change and prompt them to update their local copy of the Master Project.

Let's say I create a new project and import the Global files from the Global project that I have locally, having checked that the local Global copy is the same as the server copy. Now, other authors work on the project, and at some point one of those other authors wants to generate an output and needs to know that the Global files are up to date. Yes, I understand that the other author would make sure that their local copy of Global is up to date. But surely the import Flare project file would still be pointing to my local copy. So, would every author working on the project create their own import Flare project file?

Thanks

[Spectre]

Workflow A would consist of the Master project being imported from source control locally to the writers machines. Then imported to the child projects(All done locally). Since Master projects do not get changed often, it would be best to notify the team of the change and prompt them to update their local copy of the Master Project.

Marvin's first workflow is the exact workflow that my client's teams and I use. The Global project is bound to SVN, and each author has a working copy of it (as in, local to his or her machine). If one of us needs to make a change to the Global project, he or she alerts the rest of the team to that fact, sometimes before making the change, in case anyone objects, and sometimes afterward, 'cause maybe all he or she did was fix a typo or add an index entry. The changes are checked into SVN, and then the rest of the team can get the latest updates out of SVN and then import those updated global items into our respective Flare projects, either automatically or on demand.

The last bit is the bit I don't understand, from "the rest of the team...." onwards.

At this stage (or just before this stage), each member of the team has been verbally notified that a change to a CSS (let's say) in the global project has been made. The change to the CSS is in SVN for the global project and the team have pulled that change into their local copies of the global project.

Now the new CSS needs to be pulled into every child project, in both SVN, and for every team member locally. So I'm assuming that every team member has an import file to pull the CSS from their local global project to the local child project. But surely the import files themselves are in SVN as well aren't they? So one person is picking up an import file from SVN which has the path that is specific to someone else. They could all have differently named import files, but the setting to Auto reimport before Generate ouptut would still be picked up from SVN, so when Auto sync occurs and runs the import files, all of them would be run. I realise I must be misunderstanding the situation, but I don't understand how you're able to only run certain import files and not others, in an SVN environment.

The only way I see it working, is for one person to take responsibility for populating changes to the CSS round the projects using import files, and for the rest of the team to simply pick up the changes from SVN, without using import files.

Thanks.

[NorthEast]

So one person is picking up an import file from SVN which has the path that is specific to someone else.

If you're using a shared project, then I'd suggest keeping the master/global project in a location which will be the same for everyone; for example (a) put the project in a shared network folder, or (b) all set up the same drive mapping to your local copy.

As long as the imported project is in a consistent location, it doesn't matter who runs the project import and updates the project.

[Spectre]

So one person is picking up an import file from SVN which has the path that is specific to someone else.

If you're using a shared project, then I'd suggest keeping the master/global project in a location which will be the same for everyone; for example (a) put the project in a shared network folder, or (b) all set up the same drive mapping to your local copy.

As long as the imported project is in a consistent location, it doesn't matter who runs the project import and updates the project.

Thanks Dave. Err, how do you do option b? How would you allow everyone to map to your local machine?

Many thanks.

[NorthEast]

Err, how do you do option b? How would you allow everyone to map to your local machine?

People wouldn't be mapping to your PC.

The global project is in source control, but on each person's PC, the working folder for that project might be different.

So on Mary's PC it's c:\users\mary\projects\global, but on Bobs's PC it's c:\users\bob\projects\global.

As the import path must be the same, you could set up a drive mapping; e.g. Mary maps drive z: as c:\users\mary, and Bob maps z: as c:\users\bob.

So if you set up the project import to link from z:\projects\global, it will work for both.

It'd be easier using a network folder though, if that's possible.