Strategies for multiplatform project repository design

Question

I am looking for strategies regarding repository layout/design when dealing with multiplatform projects. Usually dependencies are:

• Project has single name/brand
• Each platform has separate source code
• Platform code shares common resources
• Design docs and other documentation is shared between platforms

I've already tried (using git) following:

Solution A:

• Each platform project resides in its own directory
• Commits go to master for all platforms

Advantages:

• clean code development
• no merging

Disadvantages:

• log is a mess, you usually need to prefix all commit logs with platform
• sometimes reversing a commit is.. not possible or very hard/messy

Solution B:

• Each platform has own branch
• When releasing a rebase is performed on each branch and then merge to master + tag

Advantages:

• Clean logs :)
• Clean separation for development pogress
• Less conflicts

Disadvantages:

• Need to merge to master
• When all platforms rebase at the same time - merge to master is HELL

I am hesitant to create per-platform repository as sharing resources might be difficult or would require additional, possibly error-prone, tasks.

Looking forward for your expertise guys.

Answer 1

Possibly another solution:

Separate into three (or more) repositories:

platform1 specific
platform2 specific
common for all platforms

You could then add the common repo into the other repositories through submodules.

Also, Google tackled a similar problem in the Android repository by developing a custom tool: repo. Repo uses a custom git repository (manifest) containing an XML file (manifest.xml or default.xml, see inside .repo/manifests) listing which Git repositories should be checked out. That way you could also create three repositories as above and another one containing the XML file to use them together, or even create branches for each platform in this manifest git.

Although I should warn that repo is very Gerrit focused.

Answer 2

This seems to be a scale-up problem. A repository normally contains a single project. Several parts of one project might share a utility module, but for small projects, the scale is not large enough to consider separating out the utility module as its own entity. However, once the utility module gets "big" or if several independent entities that share it need to be separated out, it needs to become its own (versioned) module.

My approach would be to use separate repositories, depending on how much code is involved. I'm not sure what you mean by added tasks, although it is a major refactor. The first thing I would do is make the shared resources into a stand-alone repository, and incorporate releases of that as a (version-specific) dependency in each platform build. That decouples development on each platform from a single shared resource version. Every change to the shared project requires testing every platform anyway, now you have a clean dividing line. Then you can make each project there own repository one at a time.

If you want to have a "shared release" of a project across multiple platforms, you need a "project" that is the root for the build code for that. You might consider using the shared repository for that code too, but that couples releases of the shared code to releases of the project. What you likely want, if your code has reached this level of complexity, is yet another repository just for the "meta-project" that houses your build code. Unless you have a crazy-big group of projects to work with, the builds for multiple projects could all reside in one repository, allowing them to share common code. Same problem again, but with the small scale, a single repository works. Note, all this assumes some level of automated testing :)

My experience with multi-module projects comes from using perl and java. In perl, using many independent shared modules from the CPAN is the norm. In java, modular dependencies can be handled using Apache Ivy or Maven. I used Maven in an environment that had a top level meta-project for the company and separate projects for each product (that depended on the company meta-project). Each project was free to do what it needed. Code escalated out of one project to be shared between two or more projects would become a project of its own. One particularly large project was eventually broken up into several projects all inheriting from its own "meta-project". Handling this kind of hierarchical dependency is what Maven and Ivy are built to do. We used Jenkins/Hudson as an integration server that checked cross-project builds every night automatically (assuming no-one shirked on writing tests...). Once we needed to change the website for the whole company. No problem, changed it once in the company meta-project and it was picked up automatically in the new release of every project!