BitBucket Suggestions, please!

[Stacey]

Hello:

I'm wondering if I can get some feedback/suggestions. We're currently working through the benefits and drawbacks of moving our repository from SVN to BitBucket.
Currently, we have a huge number of files (my working copy says 14.2 GB; 352, 175 files; 10, 382 folders); and we "branch" them every year so we can update different product versions (based on years) as needed (we currently have about 6 "complete" branches). (Branching became so cumbersome that new branches are just copy and paste versions of files at a specific moment in time.) One of the largest individual files we have (basically a .dita file with a large table in it) is 626 kb and takes a few minutes to open in oXygen (files of this size are rare). When we publish some of our PDFs, they can be between 600-1200 pages long. Our files are typically .dita, .ditamap, .png, and some PDF and Word files.
One of the errors we do typically get now (version 24.1) when transforming our documents is that "... is outside of the scope of the input dita/map directory". This hasn't stopped anything from being included in output to this point, but we are concerned it could become an issue in the future.
Our current repository structure is very layered (for example, \branch\writinggroup\platform\platform_product\documentname with perhaps an images folder in that to keep the images together and away from the .dita files). This was implemented in part to try to facilitate reuse - with "Common" folders at various levels in the structure used by multiple products and product lines.
It seems like BitBucket/Git has a more flat file system. We're looking for best practices for creating a "new" file structure that would be more responsive when working between it and oXygen (less lag time, easier branching or whatnot, etc.). We expect it will be a bit painful if we need to rearrange things out of our current hierarchy, but if it means less pain in another five years, we're happy to do it. (We're also completely unfamiliar with BitBucket/Git at this point, so suggestions on things that might help us get this sorted outside of determining a good file system/hierarchy are also appreciated.)
Thanks!

[Radu]

Hi Stacey,

We are using a GitHub repository for the Oxygen User's Guide DITA content:
https://github.com/oxygenxml/userguide
We have various tags and branches for each release so that we can make hot fixes to a certain release branch and this works well for us.
Each of our branches is a complete project, we do not have a separate "Commons" project linked from each branch.

One of the errors we do typically get now (version 24.1) when transforming our documents is that "... is outside of the scope of the input dita/map directory". This hasn't stopped anything from being included in output to this point, but we are concerned it could become an issue in the future.

We have this issue explained here: https://www.oxygenxml.com/doc/versions/ ... -refs.html
Indeed usually the problem is caused by references to resources outside of the DITA Map folder. As you are publishing PDF the problem may be benign but from my experience problems like this may end up causing broken links between resources especially in the HTML output.

Our current repository structure is very layered (for example, \branch\writinggroup\platform\platform_product\documentname with perhaps an images folder in that to keep the images together and away from the .dita files). This was implemented in part to try to facilitate reuse - with "Common" folders at various levels in the structure used by multiple products and product lines.

Ideally you would have multiple Git projects and they would all be self-contained. Or maybe have a single Git project containing all your projects and commons folder inside it...

It seems like BitBucket/Git has a more flat file system. We're looking for best practices for creating a "new" file structure that would be more responsive when working between it and oXygen (less lag time, easier branching or whatnot, etc.). We expect it will be a bit painful if we need to rearrange things out of our current hierarchy, but if it means less pain in another five years, we're happy to do it. (We're also completely unfamiliar with BitBucket/Git at this point, so suggestions on things that might help us get this sorted outside of determining a good file system/hierarchy are also appreciated.)

Git has most of the features SVN has. Are you currently using SVN external references to refer from one SVN project to content in another one? Git has a similar concept named "Git Submodules" which allows you to nest a Git project inside another.

As extra resources the userguide topic we have about installing the free Oxygen Git client add-on has some links to webinars at the end:
https://www.oxygenxml.com/doc/versions/ ... addon.html

Regards,
Radu

[Dmitry]

There are two handy apps for Bitbucket that might be helpful for you:
- SVN Mirror - creates a mirror between SVN and Bitbucket for a smooth, seamless migration. Also can handle complex, non-linear SVN structures.
Note: it doesn't handle SNV externals automatically.
- Git X-Modules - the closest analogue for SVN externals on Bitbucket, also a smoother and safer alternative to Git submodules.
Note: these two apps are both based on pre-receive hooks, so they can't be used simultaneously on the same repository.