Releasing output from DITA maps via Git and the Oxygen Publishing Engine

[susannecm]

Hello everyone,
my team is currently going through major organizational changes and also has to meet some new requirements.
- We are currently using Subversion as our version control system, but are planning to migrate to GitLab within the next months. For the most part, my team uses only the Subversion trunk, there are no branches.
- We will also stop releasing the documentation as part of the software and publish it on a web server instead. In this case, we will have to convert and
publish a document (i.e., a bookmap) as soon as it is ready. Currently, our Oxygen projects include sets of documents related to a product group.
- My current idea for the future is to work on a GitLab main branch by default and to add finished bookmaps to release branches. The content of release branches is then used for publication using the Publishing Engine.
Is it possible to add an entire bookmap including its referenced content from the local file system to such a release branch?
Kind regards
Susanne

[chrispitude]

Hi Susanne,

Oxygen has a Git add-on that integrates a Git client directly into the Oxygen environment. It provides many features to make Git more accessible and useful to writers. You can find more information here:

Home > Add-ons > Collaboration > Git Client Add-on

You can certainly commit any DITA content you like to a Git branch.

Our software has a documentation release every three months. Initially, we did what you described - we all worked on content in a "main" branch, then branched that to a release branch every three months. For example, here are writers A, B, and C, using that branching model:

image.png

but we ran into issues when one product released late and another product released early, because then we had to force all the early writers to wait until every late writer completed, in order to create the branch with the correct content.

To resolve this, we now have writers work directly in release branches. Every Wednesday, I run a script that performs a cascaded series of merges from earlier branches to later branches (no merge is performed if there are no changes to propagate):

image.png

This branching model works well for us. Writers work on content in whatever release branch represents that feature's intended release. They can work on a feature months in advance. They can make retroactive corrections to already-published releases and republish, and the fix is propagated forward automatically.

Of course there are conflicts from time to time during the propagation merges, but such is the nature of such multi-release work. And it gives them a reason to keep me around.

There is some related discussion here:

Oxygen XML Editor DITA (Editing and Publishing DITA Content) > Git Branch Manager

[alex_jitianu]

Hi Susanne,

Chris already gave you very useful information about Git workflows so I'll just answer this question:

Is it possible to add an entire bookmap including its referenced content from the local file system to such a release branch?

Yes, it's possible. The Git Client has a Branch Manager view in which you can create release branches.

Best regards,
Alex