Post History

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](https://softwareengineering.stackexchange.com/questions/385656/sharing-a-sub-project-and-some-users-are-git-beginners) 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?


[^1]: 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.

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](https://softwareengineering.stackexchange.com/questions/385656/sharing-a-sub-project-and-some-users-are-git-beginners) 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?


[^1]: 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.

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](https://softwareengineering.stackexchange.com/questions/385656/sharing-a-sub-project-and-some-users-are-git-beginners) 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?


[^1]: 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.

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](https://softwareengineering.stackexchange.com/questions/385656/sharing-a-sub-project-and-some-users-are-git-beginners) 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?


[^1]: 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.