Re: [PATCH] Document subproject feature

apw@us.ibm.com (Amos Waterland) writes:

Add a section to the user manual about the new subproject support.
Show how to make a subproject.

Signed-off-by: Amos Waterland <redacted>

I like the idea of having new things described in the
user manual for the new release, but with a few reservations...

Another option is to leave this as is, and make a note on the
subproject and gitattributes section that they apply only to
1.5.2 or later.  I am debating myself which one is better.

+[[subprojects]]
+Subprojects
+-----------
+
+Some large development efforts, such as embedded Linux distributions,
+are composed of a set of large projects, each with its own development
+team, but all of which are combined to produce the project as a whole.
+For example, there might be a firmware project, a hypervisor project,
+a kernel project, and a userspace project.  Note that while each
+project is conceptually independent, there are many cases in which a
+change to the hypervisor necessitates a change to the kernel, for
+example.

+In this case it is nice to be able to reason about the state of the
+entire project, but also not inconvenience each development team with
+checking out a gigantic repository that represents the entire project.

The above makes it sound as if the primary use case is to
artificially split a project that is otherwise a coherent whole,
only because split makes each piece smaller and more manageable
to handle.  While that use case is also in scope, I do not think
that is the primary one.  The above description sends a wrong
message, IMHO.

The intent of the current design of the subproject support is
more to keep track of 'subprojects' that are _not_ under your
control.  For example, an embeddd Linux appliance developer does
not control the kernel project, nor glibc, nor busybox.  He just
integrates the work by these other projects, which do not
particularly care during their own development about how _he_ is
fitting things together.

The developer however is in total control of how to fit these
pieces together, along with his own userspace, to build his
product.  He uses the subproject feature to bind these external
projects into his own project, and freeze the HEAD version for
these subprojects to match the appliance's own needs ("we will
use this version of kernel together with that version of the
out-of-tree driver").  The "embedded distribution" example you
gave matches this use case better.