MadCap Software Forums

I have read that GIT repositories could contain multiple code projects in them, however I've also read the Flare assumes that each Flare project would have it's own repository.

Can multiple Flare projects be bound to a single GIT repository?

I called into Flare about this exact issue and was told that you have to use different repos for each project and that using a single repo for multiple projects was not possible.

My Git repositories contain 3 Flare projects with no issues. However, I don't use Flare's Git integration.

Thanks Morgan, Perry,

So as I thought, Flare integration wants one repository for each each project. Almost tempted to simply use SourceTree or something, but the integration was a selling point with the other authors.

You can't use the full power of Git from Flare. Most (if not all) graphical user interfaces designed just for Git don't expose all of the commands and uses of Git, so I definitely don't expect Flare to encompass more than the Git-specific tools!

I highly recommend using source control outside of Flare, especially if you use Git. There's so much you can do with Git that Flare doesn't expose. I don't think it complicates the workflow. Actually, unbinding our projects and using Git outside of Flare actually made our lives easier.

If you have questions about Git, let me know! I love talking about this stuff!

Hi there Morgan, love to hear about your workflow for Git. I started with Git at another company where they were determined to bind and stay bound to Git through Flare despite all issues.

I want to use Git and I don't want to be bound and I was hoping you could give me some tips on workflows.

Thanks. Linda

I'm interested too! We are investigating Git and our projects would not be bound to Flare. (We're currently using SVN, not bound to Flare).

Not related to Flare, but I'd also be curious to know how you're handling binary and large files with Git? We're also investigating Git LFS for this. We build our Flare targets using TeamCity, so I'm also investigating how to best configure our build agents for Git/LFS.

Morgan is absolutely on the money here. And I love talking about it too!!

If you use standard Git tools, the question of how you group one or more projects into a repository is more how you need to branch. The approach that worked best for me and my teams was to create repos based on how product was released and doc outputs published. Think about how you need to build and publish to determine what belongs together and what should be separate.

LeslieT wrote:If you use standard Git tools, the question of how you group one or more projects into a repository is more how you need to branch. The approach that worked best for me and my teams was to create repos based on how product was released and doc outputs published. Think about how you need to build and publish to determine what belongs together and what should be separate.

That's actually how I first planned to structure our repositories—with the English project in the master branch and the translated projects in other branches, say "master-DE" and "master-FR." To work on work of those projects, a writer would branch off of either master, master-DE, or master-FR, and merge back into that branch after development. Oh and each product gets its own repository.

However, a developer that helped us set up localization with Smartling discouraged us from doing that. I forget his exact reasoning (sorry!), but basically it didn't align with the best practices followed by the engineers at my company. I'm glad it's worked out for you guys though!

We have 3 Flare projects in most of our repositories. Our repositories have this folder structure: And while working in that repository, the writer creates a development branch off of master and merges back into master after development. This works for us.
Also, last I checked, you can't have multiple Flare projects in a repository and use Flare's git integration... At least not in our setup.

It's cool that there's so many different ways to structure a git repo to fit doc needs! Yay git!

PivotGirl wrote:Hi there Morgan, love to hear about your workflow for Git. I started with Git at another company where they were determined to bind and stay bound to Git through Flare despite all issues.

I want to use Git and I don't want to be bound and I was hoping you could give me some tips on workflows.

Thanks. Linda

Hi Linda!
Why were they determined to stay bound to Git through Flare? That's so strange to me... But to each their own!

After my team decided to unbind from source control (in Flare), we just created a git repository and moved the project to that folder. Easy peasy. So what tools do we use? We started off using GitHub Desktop (you can still use it if your remote repo isn't hosted with GitHub). GitHub Desktop for Mac is pretty good. But you're a Flare user, so you're almost certainly a Windows user (unless you worked some magic to run Flare on unix, if so please share ). GitHub Desktop for Windows is not so great. It's so buggy and exposes SO FEW commands that it's almost useless. Okay that was harsh, but it's fine for the very very basics, and really not much else.

So my team decided to use Git Shell (which comes with the GitHub Desktop download... we still use Git Shell for stuff like diff'ing, but that's kind of about it, at least for me. I bet my teammates still use it a bit more). Anyways, Git Shell is really great because every Git command is at your fingertips! You just need to know which commands to use and when (and why). Oh and Git shell made my life so much easier because I can much more easily help my teammates troubleshoot or use the right Git commands for whatever it is they are trying to do. It's much easier for me to just give them the command to paste into the shell than it is for me to explain which buttons to click in GitHub Desktop (or Flare when we were integrated). It also made writing internal/team process docs much easier.

So give Git Shell a try! Really! I love it! Can you tell?! Ha.

Workflow
The workflow that works best for you will depend on a few factors, like how many contributors a repo will have and how often you publish. My team follows an adapted version of GitHub Flow (great description here, and visual here). Basically, you don't work in the master branch, ever. The master branch is ALWAYS deployable.

So how do we get work done?
For pretty much any doc project, we do this:

1. Create a new dev branch off of master
2. Do your development work, making small and meaningful commits as you go
3. Get a review (more on that later)
4. Implement review feedback
5. Submit a pull request to merge back into master when you're done
6. Ideally, someone else tests your branch and previews a merge on a machine other than yours
7. Merge the pull request
8. Republish from the master branch

Basically, don't work in the master branch, create a dev branch instead. Merge the branch into master when you're ready! And always make sure the master branch is deployable.

Reviews
You can leverage Git for reviews too! There's a few different ways to do it, but here's the most straightforward way.
Steps for the writer, when ready for the review:

1. Push your commits to the remote if you haven't already
2. Tell your reviewer what branch and what topics/content to review
3. Stay out of this branch until the review is done

Steps for the reviewer:

1. Fetch and checkout the writer's development branch
2. Turn on track changes and review the content
3. Add and commit your changes as you review
4. Push your commits to the remote

Post review steps for the writer:

1. Pull the commits made by the reviewer
2. Work through the review, accepting/rejecting changes and addressing annotations
3. Add and commit changes as you work through the review
4. Submit a pull request to merge into master when done/ready

I think that basically covers our workflow. Let me know if you have questions! I could really talk about Git all day!

And if you're going to MadWorld, you should come to my presentation about Git! It's called MadCap Flare & Git, A Love Story.

Thank you so much! I will report back on my progress. Linda

Hi,

I just stumbled upon this thread and have found it invaluable so far. My team is moving from SVN to GitHub and I'm curious about setups, workflows, and the like. Writer pain points, etc. Morgan's information was especially helpful. If anyone else has information about GitHub for documentation folks, I'd love to know more!

Thanks,
Giselle