Welcome to Software Development on Codidact!
Will you help us build our independent community of developers helping developers? We're small and trying to grow. We welcome questions about all aspects of software development, from design to code to QA and more. Got questions? Got answers? Got code you'd like someone to review? Please join us.
Comments on How should we share some content between two otherwise-independent git repositories?
Parent
How should we share some content between two otherwise-independent git repositories?
We have two teams, dev and doc, and I'd like them to have shared access (via git) to a common subset of content. Specifically, I would like the examples that are used in the doc and that are scriptable to be part of our regular (dev) tests, so we'll know if a code change has broken one of them. Right now these examples aren't in source control or regularly tested at all; I think that's bad, I want to get them checked in somewhere in a way that we can plug them in to dev's tests, and that's the reason for this question.
Elsewhere I asked about git submodule versus git subtree, but some things have changed for us since then and I'm now wondering whether the correct answer is "neither". Here are our constraints:
-
The software runs on Linux. Developers thus have Linux environments. For reasons I can't change, the doc team uses Windows but can ssh to Linux machines to run the software. (Or use locally-run VMs, but that's usually more work.)
-
Everybody uses git through the same git and Bitbucket servers. There is a doc repository and, separately, a dev repository (in different projects). The dev repository includes tests. Each test has an input script and expected output -- pretty standard stuff.
-
The dev repository is large. We don't want doc to have to check it out, especially because they wouldn't actually be able to do anything with it on Windows.
-
We would like to check in example scripts and their expected output in one place, such that the dev tests, doc, and (eventually)1 the doc build can use them. Doc would use these examples in two environments: Linux (where they can run them and thus create/maintain them), and Windows (where they can access them to use in doc).
-
Dev and doc both use the same branching policies, though not the same timing. (As is usual, doc lags dev a bit at the end of a release cycle.)
The examples I'm talking about would be used by both the dev and doc projects, which makes the examples logically a child of both. But a submodule or subtree can't have two parents (and it would probably be a bad idea anyway). In thinking about the problem, I've come to wonder whether the examples should instead be a third (top-level) repo used by both teams and independently managed. We would need to modify how the tests are run to include this other directory, which I assume would have to be external to the dev working tree. (Otherwise git would get confused about changes made therein, right?) This would effectively create a dependency from the dev repo to the examples repo, in that if you just checked out dev and ran the tests, they'd fail when they got to the references to the examples. That isn't morally pure but seems like it could be worked around, particularly if the makefile for the tests emits a suitable warning/reminder. A possibly thornier problem is that it would be each person's responsibility to be on the correct branch of the examples repo; they're separate repos so git won't help you keep them in sync.
I hadn't used git before joining this company, so I've only really seen one group's practices. How should I be thinking about this shared body of content -- separate repo, or connected in git somehow to two other repos?
-
Initially I expect that doc will cut/paste into the doc from the examples in this shared repository. That's what people do now -- they run examples locally and then copy the code and output into the doc. Yeah, not ideal, but one step at a time... Eventually I imagine the doc build being able to use something like includes to pull in stuff from the actual tested examples, someday. ↩
Post
First off, all the things @meriton said, I think overall you would be better in a single repository as your docs and code should be changing at the same rate (or should be).
Having said that if you do have two independent pieces of software which share a common piece of code you would be better to use a package system to bundle and install your shared code. This is language dependent, but examples would be npm (javascript), nuget (.NET), pip (python) etc.
The reason you want a package over a git submodule is that you want each independent repo to be in control of its own build status. For example if a change happens in a git submodule it has a potential to break downstream repos. This sucks. Instead the behaviour you want is for the downstream repos to opt into new versions of the module. This means that if a failure occurs it is initiated by the maintainers of the consuming repo, and at a time where its clear why the failure occurred.
There are some other patterns you can apply to this in really specific situations around requiring consistency but these are probably way more than you need. Heres an article I wrote about this a few years ago https://blog.staticvoid.co.nz/2017/library_vs_microservice/
1 comment thread