RFC: submodule terminology

RFC: submodule terminology

[Martin Waitz]

[-- Attachment #1: Type: text/plain, Size: 394 bytes --]

hoi :)

I think we should agree to one name for what currently is named
submodule / subproject / dirlink / gitlink.

Or use one name for the low-level plumbing (have a tree entry
which points to another commit): dirlink or gitlink and another
one for the high-level UI think: submodule or subproject.
But then we should use those names consequently.

Oppinions?

-- 
Martin Waitz

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: RFC: submodule terminology

[Johan Herland]

On Sunday 20 May 2007, Martin Waitz wrote:
> hoi :)
> 
> I think we should agree to one name for what currently is named
> submodule / subproject / dirlink / gitlink.
> 
> Or use one name for the low-level plumbing (have a tree entry
> which points to another commit): dirlink or gitlink and another
> one for the high-level UI think: submodule or subproject.
> But then we should use those names consequently.
> 
> Oppinions?


For the high-level concept, "subproject" seems to me the best 
alternative. I think it is much better than "submodule" at 
describing that the subproject is a stand-alone project/repo in
itself.

As for the low-level concept, I personally prefer "gitlink", but 
I don't have any strong feelings. The fact that "gitlink" seems 
to already be used in the code (as in resolve_gitlink_ref() etc.), 
coupled with "dirlink" being somewhat ambiguous (i.e. may also be 
interpreted as "(sym)link to directory") makes the case for me.


Have fun!

...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net

Re: RFC: submodule terminology

[Junio C Hamano]

Johan Herland <johan@herland.net> writes:

> On Sunday 20 May 2007, Martin Waitz wrote:
>> hoi :)
>> 
>> I think we should agree to one name for what currently is named
>> submodule / subproject / dirlink / gitlink.
>> 
>> Or use one name for the low-level plumbing (have a tree entry
>> which points to another commit): dirlink or gitlink and another
>> one for the high-level UI think: submodule or subproject.
>> But then we should use those names consequently.
>> 
>> Oppinions?
>
> For the high-level concept, "subproject" seems to me the best 
> alternative. I think it is much better than "submodule" at 
> describing that the subproject is a stand-alone project/repo in
> itself.

I was wondering if we can get away by just calling them
"projects", "projects containd in the superproject", etc., as I
tend to agree with Linus, who used the term "superproject
support" in his talk, that this is not really about creating
"subproject" which are somehow different from ordinary projects,
but more about supporting superprojects that can contain/point
at other projects, which we did not have before 1.5.2 happened.

> As for the low-level concept, I personally prefer "gitlink", but 
> I don't have any strong feelings.

+1

Re: RFC: submodule terminology

[Martin Waitz]

[-- Attachment #1: Type: text/plain, Size: 1200 bytes --]

hoi :)

On Mon, May 21, 2007 at 12:06:47AM +0200, Johan Herland wrote:
> For the high-level concept, "subproject" seems to me the best 
> alternative. I think it is much better than "submodule" at 
> describing that the subproject is a stand-alone project/repo in
> itself.

it may be developed independently but for the sake of the more important
bigger ("the top level project") it really is only one small part.
That and the fact that "module" is already an established term
in software makes me prefer "submodule".
For me the project is always the top-level one: the project you
currently work for.

> As for the low-level concept, I personally prefer "gitlink", but 
> I don't have any strong feelings. The fact that "gitlink" seems 
> to already be used in the code (as in resolve_gitlink_ref() etc.), 
> coupled with "dirlink" being somewhat ambiguous (i.e. may also be 
> interpreted as "(sym)link to directory") makes the case for me.

The only problem I have with gitlink is that there already was
a lot of discussion about some entirely different "gitlink", so
choosing a different name is not that bad.
Aside from that I prefer gitlink, too.

-- 
Martin Waitz

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: RFC: submodule terminology

[Johan Herland]

On Monday 21 May 2007, Junio C Hamano wrote:
> Johan Herland <johan@herland.net> writes:
> 
> > On Sunday 20 May 2007, Martin Waitz wrote:
> >> hoi :)
> >> 
> >> I think we should agree to one name for what currently is named
> >> submodule / subproject / dirlink / gitlink.
> >> 
> >> Or use one name for the low-level plumbing (have a tree entry
> >> which points to another commit): dirlink or gitlink and another
> >> one for the high-level UI think: submodule or subproject.
> >> But then we should use those names consequently.
> >> 
> >> Oppinions?
> >
> > For the high-level concept, "subproject" seems to me the best 
> > alternative. I think it is much better than "submodule" at 
> > describing that the subproject is a stand-alone project/repo in
> > itself.
> 
> I was wondering if we can get away by just calling them
> "projects", "projects containd in the superproject", etc., as I
> tend to agree with Linus, who used the term "superproject
> support" in his talk, that this is not really about creating
> "subproject" which are somehow different from ordinary projects,
> but more about supporting superprojects that can contain/point
> at other projects, which we did not have before 1.5.2 happened.

I agree that superproject is probably the best term of all. However, 
I think it's a good idea to be explicit so as to avoid unnecessary 
confusion. My vote therefore goes to "superproject/subproject" 
rather than "superproject/project".


...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net

Re: RFC: submodule terminology

[Johan Herland]

On Monday 21 May 2007, Martin Waitz wrote:
> hoi :)
> 
> On Mon, May 21, 2007 at 12:06:47AM +0200, Johan Herland wrote:
> > For the high-level concept, "subproject" seems to me the best 
> > alternative. I think it is much better than "submodule" at 
> > describing that the subproject is a stand-alone project/repo in
> > itself.
> 
> it may be developed independently but for the sake of the more important
> bigger ("the top level project") it really is only one small part.
> That and the fact that "module" is already an established term
> in software makes me prefer "submodule".
> For me the project is always the top-level one: the project you
> currently work for.

"The project you currently work for" depends on your POV. But I agree
that using the term "project" alone might be confusing. That's why I'd
rather talk about "superproject" and "subproject". That way, there's
no ambiguity at all.

> > As for the low-level concept, I personally prefer "gitlink", but 
> > I don't have any strong feelings. The fact that "gitlink" seems 
> > to already be used in the code (as in resolve_gitlink_ref() etc.), 
> > coupled with "dirlink" being somewhat ambiguous (i.e. may also be 
> > interpreted as "(sym)link to directory") makes the case for me.
> 
> The only problem I have with gitlink is that there already was
> a lot of discussion about some entirely different "gitlink", so
> choosing a different name is not that bad.
> Aside from that I prefer gitlink, too.

The term "gitlink" is ambiguous/confusing? I didn't know. What's the 
other meaning of gitlink?

(Unless you're talking about gitlink as in "gitlink:git[7]" which 
appears all over our asciidoc documentation, but I don't think that 
counts...)


Have fun!

...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net

Re: RFC: submodule terminology

[Martin Waitz]

[-- Attachment #1: Type: text/plain, Size: 303 bytes --]

hoi :)

On Mon, May 21, 2007 at 01:16:24AM +0200, Johan Herland wrote:
> The term "gitlink" is ambiguous/confusing? I didn't know. What's the 
> other meaning of gitlink?

there was some talk about lightweight checkouts using some .gitlink
file instead of a .git directory.

-- 
Martin Waitz

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: RFC: submodule terminology

[Eric Lesh]

On Mon, 2007-05-21 at 01:39 +0200, Martin Waitz wrote:
> hoi :)
> 
> On Mon, May 21, 2007 at 01:16:24AM +0200, Johan Herland wrote:
> > The term "gitlink" is ambiguous/confusing? I didn't know. What's the 
> > other meaning of gitlink?
> 
> there was some talk about lightweight checkouts using some .gitlink
> file instead of a .git directory.
> 

This was my project, but if I end up trying to do lightweight checkouts
I'll avoid a .gitlink file most likely (and go with something
in .git/config instead).  Gitlink is therefore quite safe.

-Eric

Re: RFC: submodule terminology

[Raimund Bauer]

On Sun, 2007-05-20 at 15:59 -0700, Junio C Hamano wrote:
> I was wondering if we can get away by just calling them
> "projects", "projects containd in the superproject", etc., as I
> tend to agree with Linus, who used the term "superproject
> support" in his talk, that this is not really about creating
> "subproject" which are somehow different from ordinary projects,
> but more about supporting superprojects that can contain/point
> at other projects, which we did not have before 1.5.2 happened.

The "super" or "sub" only comes from where in a hierarchy it is used.
Somewhere in the middle of the hierarchy it would be both?

I'd have said a repository can have many "modules" or "projects", and
each of those can have several branches. A module can hold other
modules, but from its POV also be part of a super-module (or
superproject), we just have to take care to not build loops.

Is my view of the world correct so far?

-- 
best regards

  Ray

Re: RFC: submodule terminology

[Shawn O. Pearce]

Raimund Bauer <ray007@gmx.net> wrote:
> On Sun, 2007-05-20 at 15:59 -0700, Junio C Hamano wrote:
> > I was wondering if we can get away by just calling them
> > "projects", "projects containd in the superproject", etc., as I
> > tend to agree with Linus, who used the term "superproject
> > support" in his talk, that this is not really about creating
> > "subproject" which are somehow different from ordinary projects,
> > but more about supporting superprojects that can contain/point
> > at other projects, which we did not have before 1.5.2 happened.
> 
> The "super" or "sub" only comes from where in a hierarchy it is used.
> Somewhere in the middle of the hierarchy it would be both?

Yes.  Of course.
 
> I'd have said a repository can have many "modules" or "projects", and
> each of those can have several branches. A module can hold other
> modules, but from its POV also be part of a super-module (or
> superproject), we just have to take care to not build loops.

You cannot build a loop.  OK, let me rephrase:

I can build a loop where at one point in time project A uses project
B as his subproject; then later I can have project B use project
A as a subproject.  That's a loop.  But the commits themselves are
not in a cycle.  There is a specific version of A that requires a
specific version of B, and there is a different version of B that
requires an entirely different version of A.

This loop really just means we have to be smart about how we switch
between versions of a project.  Just like if B is required in one
version of superproject A and not in another; when I switch back
and forth in A I expect B to appear/disappear.  And I expect it
to work on an airplane, where network access to reclone B is not
available (or is too costly).  That means we have to "hide" B when
its not needed.

If you can actually form a loop where version of A requires version
of B and version of B requires the version of A that requires the
version of B... that's a SHA-1 hash collision.  If you can make
them at will, you probably can make some good money illegally...

> Is my view of the world correct so far?

Yes.

-- 
Shawn.