Flare 12, GIT, and importing

This forum is for all Flare issues related to using Source Control.
Post Reply
lanval
Propeller Head
Posts: 36
Joined: Wed Jul 19, 2006 12:21 pm
Location: Winnipeg MB

Flare 12, GIT, and importing

Post by lanval »

We are a multi-author environment and we are trying to setup GIT as our source control, but I have been encountering some issues. I've read a fair number of posts in these forums, but I can't seem to get Git.

Our IT rep (who is familiar with CSV, but not Git), set up a network file share with a Git repository for testing purposes (\\GITHOST\GITRepository)

Unfortunately, IT is currently in a the middle of a large, long-term project and getting their time is difficult, so I'm trying to troubleshoot this myself - as much as I can.

What I have done:
  1. I copied the initial project (a copy of our Global project) into the \\GITHOST\GITRepository directory.
  2. I opened that project and bound it. Looks correct in Source Control Explorer:
    - Provider Type: Git
    - Database: file://GITHOST/GITRepository/.git
    - Database Folder: file://GITHOST/GITRepository/
This is now my Master.

My understanding is that I should not work in the remote Master, rather I should:
  1. Import this project into a new, local project.
  2. Create a branch in the imported project.
  3. Make my edits.
  4. Commit the changes.
  5. Synchronise the changes back into the Master repository/project.
If I'm wrong about any of this, please let me know…

My main issue occurs when I try to import the project into the new local project.
  1. I opened Flare.
  2. From the Source Control Explorer, I selected Import Project.
  3. In the Wizard, I selected Git and for the Remote field I entered \\githost\GITRepository.
  4. I entered my name and my e-mail address and then for the Save Per field I selected Project.
  5. I clicked Next.
  6. Even though the cursor was blinking in the Project file field, I was unable to manually enter anything, so I clicked Browse…
  7. I immediately got an error
    Could not clone remote file://GITHOST/GITRepository for the following reasons: Failed to resolve path 'file://githost/GitRepository': The filename, directory name, or volume label syntax is incorrect.
    Closing that error dialog the progress dialog which states:
    Cloning Git repository…
    Source Control: Failed to resolve path 'file://githost/GitRepository': The filename, directory name, or volume label syntax is incorrect.
    : Could not authenticate.
git-flare-error.png
And that’s as far as it goes…

Suggestions?
You do not have the required permissions to view the files attached to this post.
Cheers,
Michael
morganhancock
Propeller Head
Posts: 13
Joined: Wed Feb 10, 2016 8:35 am

Re: Flare 12, GIT, and importing

Post by morganhancock »

What type of transport protocols are set up on that server? Do you have read/write access to the repo? Flare is telling you that it cannot locate that Git repo or the project file... I'm not sure which since Flare's error message isn't clear (the error message makes it seem like it's looking for a file). Have you tried entering \\GITHOST\GITRepository\ProjectName.flprj ?

What's happening is that Flare is trying to clone the remote repository so that you have a local version of that repository, but something's not working. You could try cloning the repository outside of Flare, using Git Shell or another tool. How you clone it depends on the transport protocols of the \\GITHOST\GITRepository (how you access the repo... ssh, http, https, etc.). Cloning it outside of Flare would be easier, in my opinion.

Just some other notes...
The remote repository isn't your "Master"; it just contains your master branch, called origin/Master. But it can contain other branches too. You're correct that you should not work in the remote Master branch (origin/Master), but you shouldn't work in any of the remote branches (or even in your local Master branch, if you want to follow best practices). With Git, you get a remote repository and a clone of that repository on your machine. You should work locally (in the clone of that repo) and push your development branch (with all the changes and commits you've made) to the remote repo. Then when you're happy with the development branch, you can merge it into Master (or origin/Master, depending on your workflow).
lanval
Propeller Head
Posts: 36
Joined: Wed Jul 19, 2006 12:21 pm
Location: Winnipeg MB

Re: Flare 12, GIT, and importing

Post by lanval »

I'm able to use SourceTree to work in the origin repo. I was able to clone a local copy as well, so I don't think it is a permission or incorrect network reference. I snagged some IT time today, perhaps they can suggest something.

Morgan, thanks for the clarification in your note. That cleared some things up. but, I wonder about branches. Are you always working in a created branch in you local? We never have multiple authors in one project, is branching required by Git to properly commit, stage and push; or can I work in the Master branch of the local clone?
Cheers,
Michael
morganhancock
Propeller Head
Posts: 13
Joined: Wed Feb 10, 2016 8:35 am

Re: Flare 12, GIT, and importing

Post by morganhancock »

My team follows GitHub flow (you can find a good article about it here:http://scottchacon.com/2011/08/31/github-flow.html).

We don't work directly in the Master branch. We want Master to always be safe to publish from, so anything in Master is complete and publication-ready. This means that we can't have in-progress work in the Master branch, so we develop in other branches and submit Pull Requests to merge our work into the Master branch (when we deem it "publication-ready").

So here's an example... Say I need to document a new feature. I'd create a branch off of Master and name it Feature_1. In the Feature_1 branch, I edit some existing topics and add new topics. I commit my changes and new topics to the Feature_1 branch and then push that branch to the remote repository (where it would be origin/Feature_1). My teammates could then pull down Feature_1 to their machine (their local clone of our shared repo), and work in that branch as well (depending on your workflow, maybe they are adding content about this feature as well or just editing your work). Once the documentation is complete for this new feature, I'd submit a Pull Request to merge Feature_1 into Master.

That's a simple, one development-branch example. You can do this with many branches and many contributors. Say a teammate was working on documenting a separate feature. She'd create a branch off of Master and name it Feature_2. While you are working in Feature_1, she works in Feature_2 (or you both work in both branches... it doesn't matter as long as you only document the first feature in Feature_1 and the second in Feature_2) . This workflow is really beneficial if, for example, you need to publish the Feature_1 content this week, but you can't publish the other feature content (documented in Feature_2) until the feature releases next month. After you merge Feature_1 into Master, your teammate would update Feature_2 from Master to get that newly merged content. This step is essential to avoiding merging errors when she's ready to merge Feature_2 into Master.

So to your question, no, you technically don't have to branch and each author can work in Master on their local clone. But that eliminates Git's most awesome feature, the ease of branching! Also, it could complicate your workflow, depending on how you publish and separate in-progress and publication-ready content.

Git has been great for my team because we can now easily collaborate and share in-progress work, without worrying about in-progress content sneaking into our published output. Mistakes do happen, but we haven't been able to destroy anything yet! Git is great because it tracks history, not individual changes, so it's easy to fix mistakes by rolling back to the last stable point in your repo's history.

I'm happy to talk more if you have more questions! If you can't tell, I really love Git!
MatrixDee
Jr. Propeller Head
Posts: 2
Joined: Wed Oct 19, 2016 7:17 am

Re: Flare 12, GIT, and importing

Post by MatrixDee »

Thanks everyone, this thread has been very helpful!

Regarding the GitHub workflow:
We don't work directly in the Master branch. We want Master to always be safe to publish from, so anything in Master is complete and publication-ready. This means that we can't have in-progress work in the Master branch, so we develop in other branches and submit Pull Requests to merge our work into the Master branch (when we deem it "publication-ready").
Does the Flare Source Control feature support Pull Requests and merging branches? We have a way to do this from our Git client. However, if our authors can complete the GitHub workflow entirely in Flare, that would be preferable. Even in a single-authoring scenario, I don't see an option in Flare to merge my development branch to the master.
TimElhajj
Jr. Propeller Head
Posts: 4
Joined: Mon Aug 28, 2017 3:21 pm

Re: Flare 12, GIT, and importing

Post by TimElhajj »

morganhancock wrote: I'm happy to talk more if you have more questions! If you can't tell, I really love Git!
Hi!

My team is currently exploring git and using branches in much the way you describe. One issue we haven't quite figured out is how to do reviews before we publish to live. Right now we have a single test site where we publish drafts for review. The way this currently works is that we use condition tags and different targets in Flare to suppress (on the public site) material that is still in review. When it's time to review we publish to a non public site and provide reviewers with links to the topics that have changed.

Our goal is to find a way to use the branching in git to do away with all the tagging with Flare conditions. So the problem we can't figure out is how two writers, each working on a separate feature in a distinct branch, both need to publish their changes to the nonpublic site for review. One solution that's been proposed is to create multiple sites, each with only the changes in the branch.

test.example.com/productA/branch1
test.example.com/productA/branch2

But that would be a big change from what we are doing now. Is there a better way to combine all the changes in all the branches to publish to the test site, while still preserving the ability to publish from master as needed? How do others tackle this problem?

In the linked GitHub-flow article, review is dealt with by using a pull request, but this is meant for a developer to look at the diffs and would also be a big change from what we're currently doing. Are other UA teams using pull requests for reviews?
Christina_E
Jr. Propeller Head
Posts: 4
Joined: Wed Jul 29, 2015 8:42 am

Re: Flare 12, GIT, and importing

Post by Christina_E »

We have been using git for our source control for a couple of years now, but are just starting to use git branches and pull requests for developer reviews and updates. For operational reasons, we are aligning our documentation processes with our development processes -- which means that much of what can be done in Flare is being carried out at the command line or in the GitHub user interface.

Our process is as follows:
- At a command prompt, we pull the latest master branch;
- Still at the command prompt, we then create a new, temporary branch off the master, copy that branch locally, and switch branches to the new branch (incidentally, we name the branch with the JIRA reference #);
- In Flare, we verify that we're working in the new branch, and then proceed with the updates and save the files;
- Back at the command prompt, we add/commit/push the changes to the new branch on the git server;
- In the GitHub user interface, we create a new pull request and add the appropriate reviewers;
- When the back and forth of the review is complete, in the GitHub user interface, we create and process the merge;
- Back at the command prompt, we commit and push the merge;
- If any conflicts are identified (we are multiple writers), we can launch Beyond Compare from the command line to resolve the conflicts;
- We run git status and git log to ensure that our changes were successfully pushed to the master branch;
- We delete the new, temporary branch.

One of the issues we've run across is that the git PR process adds lines of text related to the PR to the Flare source file. The following new lines encompass the modified content: <<<<<<< HEAD, >>>>>>> parent of <PR commit, including the commit comment>; </html> is added at the end of the file. Flare cannot resolve these additional lines of text, and throws an error message that the file contains invalid xml. Other than manually editing text versions of the Flare files to resolve the invalid xml, I'm at a loss for what to do.

Feedback and suggestions are welcomed. Thanks!
Christina
TimElhajj
Jr. Propeller Head
Posts: 4
Joined: Mon Aug 28, 2017 3:21 pm

Re: Flare 12, GIT, and importing

Post by TimElhajj »

Christina_E wrote: One of the issues we've run across is that the git PR process adds lines of text related to the PR to the Flare source file. The following new lines encompass the modified content: <<<<<<< HEAD, >>>>>>> parent of <PR commit, including the commit comment>; </html> is added at the end of the file. Flare cannot resolve these additional lines of text, and throws an error message that the file contains invalid xml. Other than manually editing text versions of the Flare files to resolve the invalid xml, I'm at a loss for what to do.

Feedback and suggestions are welcomed. Thanks!
Christina
Yes, we get those lines, too. Those are the lines git adds to identify conflicts. Beyond Compare is one of the best tools to resolve the conflicts but whatever you use, it always involves removing those lines manually. If there is another way to do it, I don't know what it is.

I don't get conflicts with every merge, but some merges typically always have conflicts. For example, if I am working on something in a feature branch for a while and I update master, then I will need to rebase the working branch, and that often involves resolving lots of conflicts.
Post Reply