Re: [1.8.0] reorganize the mess that the source tree has become

Re: [1.8.0] reorganize the mess that the source tree has become

[George Spelvin]

For what it's worth, I don't see the "cleanup".

If it significantly reduced the size of the largest directory,
that would be a win.  But moving everything into src/ doesn't
do that.

If there's a way to divide the source into cohesive subunits, that
would be great.  A programmer could ignore whole subdirectories
when working on something.

But just moving the whole existing pile into a subdirectory "because
everyone else does it" is not a reason; that's superstition.

Having to type "src/" a lot more often is definitely a downside.

Heck, that's one thing I actively dislike about GNU autoconf conventions.

If there's a compelling reason to change, could someone please describe it?

Re: [1.8.0] reorganize the mess that the source tree has become

[Erik Faye-Lund]

On Wed, Feb 2, 2011 at 3:29 AM, George Spelvin <linux@horizon.com> wrote:
> If there's a compelling reason to change, could someone please describe it?

I think the most compelling argument I can think of is that it makes
top-level entries like Documentation, RelNotes, COPYING, README and
INSTALL easier to spot when doing "ls". For some users (first-time
hackers etc) that's a pretty big plus, I'd think.

Re: [1.8.0] reorganize the mess that the source tree has become

[Pascal Obry]

Le 02/02/2011 09:31, Erik Faye-Lund a écrit :
> On Wed, Feb 2, 2011 at 3:29 AM, George Spelvin <linux@horizon.com> wrote:
>> If there's a compelling reason to change, could someone please describe it?
> 
> I think the most compelling argument I can think of is that it makes
> top-level entries like Documentation, RelNotes, COPYING, README and
> INSTALL easier to spot when doing "ls". For some users (first-time
> hackers etc) that's a pretty big plus, I'd think.

I was about to say that too. That's an argument strong enough I would
say. Today it is hard to see the structure.

-- 

--|------------------------------------------------------
--| Pascal Obry                           Team-Ada Member
--| 45, rue Gabriel Peri - 78114 Magny Les Hameaux FRANCE
--|------------------------------------------------------
--|    http://www.obry.net  -  http://v2p.fr.eu.org
--| "The best way to travel is by means of imagination"
--|
--| gpg --keyserver keys.gnupg.net --recv-key F949BD3B

Re: [1.8.0] reorganize the mess that the source tree has become

[Nicolas Pitre]

On Tue, 1 Feb 2011, George Spelvin wrote:

> For what it's worth, I don't see the "cleanup".
> 
> If it significantly reduced the size of the largest directory,
> that would be a win.  But moving everything into src/ doesn't
> do that.
> 
> If there's a way to divide the source into cohesive subunits, that
> would be great.  A programmer could ignore whole subdirectories
> when working on something.
> 
> But just moving the whole existing pile into a subdirectory "because
> everyone else does it" is not a reason; that's superstition.

There is no superstition here, simply basic elegance.

When you pick up a book from a shelf, do you see the actual content of 
the book printed right from the inside of the cover page, and the table 
of content tossed in the margin?  Would you construct a book yourself 
that way?

A nice source tree should be organized with a minimum of hierarchical 
structure.  To a newbie wanting to contribute to Git, it is rather 
frightening to cd into the git directory and see that ls generates more 
than 280 entries.  That simply looks sloppy.  And this gets much worse 
after a make.

The top directory should make different things stand out much more 
clearly, like a preface and a table of content.  You have the 
documentation here, the source there, the tests there, a clearly visible 
README file, etc.  If the src directory has about the same relative 
number of files after a move that's fine.  At least you should expect 
_only_ source files in there (and possibly their by-products), and not 
other types of data buried into the mix.

> Having to type "src/" a lot more often is definitely a downside.

Come on.  This is a rather egocentric argument without much substance.

> Heck, that's one thing I actively dislike about GNU autoconf conventions.

This has _nothing_ about any autoconf convention.  GNU autoconf requires 
stupid things like having a bunch of files such as CREDITS, INSTALL, 
CHANGELOG, and other whatnots even if you have nothing to put in them, 
in which case they still have to be there but empty.  It also dictates 
the exact name your directories must have, etc.

I'm not proposing a tree reorganization because GNU autoconf commands 
it, but rather because this is a sensible thing to do.

> If there's a compelling reason to change, could someone please describe it?

It's about the third time I'm putting forward arguments for this.  
Please see the list archive.

P.S. the netiquette on busy mailing lists recommends that you preserve 
all the email addresses that were listed as recipients on the message 
you reply to.  That would be highly appreciated.


Nicolas

Re: [1.8.0] reorganize the mess that the source tree has become

[Miles Bader]

Nicolas Pitre <nico@fluxnic.net> writes:
>> But just moving the whole existing pile into a subdirectory "because
>> everyone else does it" is not a reason; that's superstition.
>
> There is no superstition here, simply basic elegance.

"basic elegance" is hardly well-defined, and although there are probably
issues on which there's general agreement, this doesn't appear to be one
of them.

>> Having to type "src/" a lot more often is definitely a downside.
>
> Come on.  This is a rather egocentric argument without much substance.

It certainly has more substance than hand-waving like "basic elegance"
though...

Some slightly more concrete arguments have been:

  Pro-src:  Big top-level dir scares newbs
  Anti-src: Extra typing is annoying

I'm not really against a "src/" subdir, but it seems mostly a matter of
taste, and I've seen plenty of projects where the src/ directory seemed
pretty pointless...

-Miles

-- 
Politics, n. A strife of interests masquerading as a contest of
principles. The conduct of public affairs for private advantage.

Re: [1.8.0] reorganize the mess that the source tree has become

[Andreas Schwab]

Nicolas Pitre <nico@fluxnic.net> writes:

> This has _nothing_ about any autoconf convention.  GNU autoconf requires 
> stupid things like having a bunch of files such as CREDITS, INSTALL, 
> CHANGELOG, and other whatnots even if you have nothing to put in them, 
> in which case they still have to be there but empty.  It also dictates 
> the exact name your directories must have, etc.

That's automake, not autoconf (and only the default automake operation).

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: [1.8.0] reorganize the mess that the source tree has become

[Eugene Sajine]

On Thu, Feb 3, 2011 at 1:16 AM, Nicolas Pitre <nico@fluxnic.net> wrote:
> On Tue, 1 Feb 2011, George Spelvin wrote:
>
>> For what it's worth, I don't see the "cleanup".
>>
>> If it significantly reduced the size of the largest directory,
>> that would be a win.  But moving everything into src/ doesn't
>> do that.
>>
>> If there's a way to divide the source into cohesive subunits, that
>> would be great.  A programmer could ignore whole subdirectories
>> when working on something.
>>
>> But just moving the whole existing pile into a subdirectory "because
>> everyone else does it" is not a reason; that's superstition.
>
> There is no superstition here, simply basic elegance.
>
> When you pick up a book from a shelf, do you see the actual content of
> the book printed right from the inside of the cover page, and the table
> of content tossed in the margin?  Would you construct a book yourself
> that way?
>
> A nice source tree should be organized with a minimum of hierarchical
> structure.  To a newbie wanting to contribute to Git, it is rather
> frightening to cd into the git directory and see that ls generates more
> than 280 entries.  That simply looks sloppy.  And this gets much worse
> after a make.
>
> The top directory should make different things stand out much more
> clearly, like a preface and a table of content.  You have the
> documentation here, the source there, the tests there, a clearly visible
> README file, etc.  If the src directory has about the same relative
> number of files after a move that's fine.  At least you should expect
> _only_ source files in there (and possibly their by-products), and not
> other types of data buried into the mix.
>
>> Having to type "src/" a lot more often is definitely a downside.
>
> Come on.  This is a rather egocentric argument without much substance.
>
>> Heck, that's one thing I actively dislike about GNU autoconf conventions.
>
> This has _nothing_ about any autoconf convention.  GNU autoconf requires
> stupid things like having a bunch of files such as CREDITS, INSTALL,
> CHANGELOG, and other whatnots even if you have nothing to put in them,
> in which case they still have to be there but empty.  It also dictates
> the exact name your directories must have, etc.
>
> I'm not proposing a tree reorganization because GNU autoconf commands
> it, but rather because this is a sensible thing to do.
>
>> If there's a compelling reason to change, could someone please describe it?
>
> It's about the third time I'm putting forward arguments for this.
> Please see the list archive.
>
> P.S. the netiquette on busy mailing lists recommends that you preserve
> all the email addresses that were listed as recipients on the message
> you reply to.  That would be highly appreciated.
>
>
> Nicolas
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>

I'm not a hacker, but a user who had sometimes peeked into the git
sources. Unbelievable mess... Impossible to see the structure in
command line interface.
I totally agree with Nicolas here.
Folders were invented for a reason.

IMHO
src for source code
build for build by-products
tests for tests

Come on, give us some love, please!;)

Thanks,
Eugene

Re: [1.8.0] reorganize the mess that the source tree has become

[Hilco Wijbenga]

On 3 February 2011 10:46, Eugene Sajine <euguess@gmail.com> wrote:
> On Thu, Feb 3, 2011 at 1:16 AM, Nicolas Pitre <nico@fluxnic.net> wrote:
>> On Tue, 1 Feb 2011, George Spelvin wrote:
>>
>>> For what it's worth, I don't see the "cleanup".
>>>
>>> If it significantly reduced the size of the largest directory,
>>> that would be a win.  But moving everything into src/ doesn't
>>> do that.
>>>
>>> If there's a way to divide the source into cohesive subunits, that
>>> would be great.  A programmer could ignore whole subdirectories
>>> when working on something.
>>>
>>> But just moving the whole existing pile into a subdirectory "because
>>> everyone else does it" is not a reason; that's superstition.
>>
>> There is no superstition here, simply basic elegance.
>>
>> When you pick up a book from a shelf, do you see the actual content of
>> the book printed right from the inside of the cover page, and the table
>> of content tossed in the margin?  Would you construct a book yourself
>> that way?
>>
>> A nice source tree should be organized with a minimum of hierarchical
>> structure.  To a newbie wanting to contribute to Git, it is rather
>> frightening to cd into the git directory and see that ls generates more
>> than 280 entries.  That simply looks sloppy.  And this gets much worse
>> after a make.
>>
>> The top directory should make different things stand out much more
>> clearly, like a preface and a table of content.  You have the
>> documentation here, the source there, the tests there, a clearly visible
>> README file, etc.  If the src directory has about the same relative
>> number of files after a move that's fine.  At least you should expect
>> _only_ source files in there (and possibly their by-products), and not
>> other types of data buried into the mix.
>>
>>> Having to type "src/" a lot more often is definitely a downside.
>>
>> Come on.  This is a rather egocentric argument without much substance.
>>
>>> Heck, that's one thing I actively dislike about GNU autoconf conventions.
>>
>> This has _nothing_ about any autoconf convention.  GNU autoconf requires
>> stupid things like having a bunch of files such as CREDITS, INSTALL,
>> CHANGELOG, and other whatnots even if you have nothing to put in them,
>> in which case they still have to be there but empty.  It also dictates
>> the exact name your directories must have, etc.
>>
>> I'm not proposing a tree reorganization because GNU autoconf commands
>> it, but rather because this is a sensible thing to do.
>>
>>> If there's a compelling reason to change, could someone please describe it?
>>
>> It's about the third time I'm putting forward arguments for this.
>> Please see the list archive.
>>
>> P.S. the netiquette on busy mailing lists recommends that you preserve
>> all the email addresses that were listed as recipients on the message
>> you reply to.  That would be highly appreciated.
>>
>>
>> Nicolas
>> --
>> To unsubscribe from this list: send the line "unsubscribe git" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>>
>
> I'm not a hacker, but a user who had sometimes peeked into the git
> sources. Unbelievable mess... Impossible to see the structure in
> command line interface.
> I totally agree with Nicolas here.
> Folders were invented for a reason.
>
> IMHO
> src for source code
> build for build by-products
> tests for tests
>
> Come on, give us some love, please!;)

Another one from the peanut gallery. :-) I wholeheartedly agree with
both Nicolas and Eugene.

Quite frankly, I'm surprised there are (presumably experienced)
developers who do not immediately see the value of a little
organization. Surely, given the use of code conventions, formatting
rules, etcetera, the obvious one step further is to also organize
where the files go?

(Given that I'm just a lurker I promise to leave it at this. I just
wanted to show Nicolas a little support.)

Re: [1.8.0] reorganize the mess that the source tree has become

[Miles Bader]

Hilco Wijbenga <hilco.wijbenga@gmail.com> writes:
> Quite frankly, I'm surprised there are (presumably experienced)
> developers who do not immediately see the value of a little
> organization. Surely, given the use of code conventions, formatting
> rules, etcetera, the obvious one step further is to also organize
> where the files go?

I think one of the problems is that what's been suggested seems like
window-dressing.  Moving everything into src/ and calling it "organized"
doesn't actually accomplish much other than perhaps making the README
file more visible to newbs; things are _still_ a mess, just a mess with
four more letters...

-Miles

-- 
Back, n. That part of your friend which it is your privilege to contemplate in
your adversity.

Re: [1.8.0] reorganize the mess that the source tree has become

[Tor Arntsen]

On Fri, Feb 4, 2011 at 03:06, Miles Bader <miles@gnu.org> wrote:
> Hilco Wijbenga <hilco.wijbenga@gmail.com> writes:
>> Quite frankly, I'm surprised there are (presumably experienced)
>> developers who do not immediately see the value of a little
>> organization. Surely, given the use of code conventions, formatting
>> rules, etcetera, the obvious one step further is to also organize
>> where the files go?
>
> I think one of the problems is that what's been suggested seems like
> window-dressing.  Moving everything into src/ and calling it "organized"
> doesn't actually accomplish much other than perhaps making the README
> file more visible to newbs; things are _still_ a mess, just a mess with
> four more letters...

What Miles says is my feeling as well. And having a 'bin/' as was suggested
in one post doesn't make much sense to me either - if you want your compiled
output to go elsewhere than the source directory then the normal way of doing
that is to do and out-of-tree build (so if that's not working - I have
not checked -
then that's something which would be worth looking into.)

-Tor

Re: [1.8.0] reorganize the mess that the source tree has become

[Jakub Narebski]

Tor Arntsen <tor@spacetec.no> writes:
> On Fri, Feb 4, 2011 at 03:06, Miles Bader <miles@gnu.org> wrote:
> > Hilco Wijbenga <hilco.wijbenga@gmail.com> writes:
>>>
>>> Quite frankly, I'm surprised there are (presumably experienced)
>>> developers who do not immediately see the value of a little
>>> organization. Surely, given the use of code conventions, formatting
>>> rules, etcetera, the obvious one step further is to also organize
>>> where the files go?
>>
>> I think one of the problems is that what's been suggested seems like
>> window-dressing.  Moving everything into src/ and calling it "organized"
>> doesn't actually accomplish much other than perhaps making the README
>> file more visible to newbs; things are _still_ a mess, just a mess with
>> four more letters...
> 
> What Miles says is my feeling as well. And having a 'bin/' as was suggested
> in one post doesn't make much sense to me either - if you want your compiled
> output to go elsewhere than the source directory then the normal way of doing
> that is to do and out-of-tree build (so if that's not working - I have
> not checked - then that's something which would be worth looking into.)

It is about supporting 'srcdir', isn't it?

BTW. what about using 'lib/' directory?
-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: [1.8.0] reorganize the mess that the source tree has become

[Erik Faye-Lund]

On Fri, Feb 4, 2011 at 3:06 AM, Miles Bader <miles@gnu.org> wrote:
> Hilco Wijbenga <hilco.wijbenga@gmail.com> writes:
>> Quite frankly, I'm surprised there are (presumably experienced)
>> developers who do not immediately see the value of a little
>> organization. Surely, given the use of code conventions, formatting
>> rules, etcetera, the obvious one step further is to also organize
>> where the files go?
>
> I think one of the problems is that what's been suggested seems like
> window-dressing.  Moving everything into src/ and calling it "organized"
> doesn't actually accomplish much other than perhaps making the README
> file more visible to newbs; things are _still_ a mess, just a mess with
> four more letters...

FWIW, I don't quite see what's wrong with "window dressing" here.
Making those files more visible is a good thing, IMO.

But I'm not so sure I agree that the rest of the source tree is such a
mess that everyone makes it out to be. OK, there's a lot of
source-files on the top-level (which would be the src-level with this
change), but why is that such a bad thing? And if this is a big deal,
perhaps moving libgit-sources to a separate folder would help?

[1.8.0] Re: reorganize the mess that the source tree has become

[Nicolas Sebrecht]

The 04/02/11, Miles Bader wrote:
> Hilco Wijbenga <hilco.wijbenga@gmail.com> writes:
> > Quite frankly, I'm surprised there are (presumably experienced)
> > developers who do not immediately see the value of a little
> > organization. Surely, given the use of code conventions, formatting
> > rules, etcetera, the obvious one step further is to also organize
> > where the files go?
> 
> I think one of the problems is that what's been suggested seems like
> window-dressing.  Moving everything into src/ and calling it "organized"
> doesn't actually accomplish much other than perhaps making the README
> file more visible to newbs; things are _still_ a mess, just a mess with
> four more letters...

So it would be an ordered mess, at least. The current amount of files in
the root directory do make things harder for people not already familiar
with the content. FMHO, moving the source files into a subdirectory
could be only a first step to the good direction.

-- 
Nicolas Sebrecht

Re: [1.8.0] Re: reorganize the mess that the source tree has become

[Drew Northup]

On Fri, 2011-02-04 at 19:15 +0100, Nicolas Sebrecht wrote:
> The 04/02/11, Miles Bader wrote:
> > Hilco Wijbenga <hilco.wijbenga@gmail.com> writes:
> > > Quite frankly, I'm surprised there are (presumably experienced)
> > > developers who do not immediately see the value of a little
> > > organization. Surely, given the use of code conventions, formatting
> > > rules, etcetera, the obvious one step further is to also organize
> > > where the files go?
> > 
> > I think one of the problems is that what's been suggested seems like
> > window-dressing.  Moving everything into src/ and calling it "organized"
> > doesn't actually accomplish much other than perhaps making the README
> > file more visible to newbs; things are _still_ a mess, just a mess with
> > four more letters...
> 
> So it would be an ordered mess, at least. The current amount of files in
> the root directory do make things harder for people not already familiar
> with the content. FMHO, moving the source files into a subdirectory
> could be only a first step to the good direction.

Nicolas,
Having once upon a time (in CVS days) taken over a project that was
neatly organized into tons of folders I can say that more folders is not
always better.
If you are organizing things into modules by folders, and those things
are mutually exclusive pre-compilation then doing so may make sense. If
the folders ADD value to the project by adding organization--as opposed
to hiding disorganization--then they may have value.
>From my meager hacking thus far (working on making utf-16 a more
user-friendly experience out-of-the-box) I have found that none of this
is true (thus far) with the git codebase. In fact the one thing that
would have been useful is more in-code--and/or separate
API-ish--documentation (it took me waaaay too long to figure out how git
add, aka git-add, works), but I am too much of a realist to expect that
to change much. I most certainly DO NOT recommend that a mess of patches
be submitted to Junio to fix it (document what you are working on as you
see fit; I work on too many things to not document fairly extensively).
I approach codebase reorganization the same way. I have seen the
destructive things it can do to a project when it becomes an end unto
itself separate from the primary focus. In fact, what killed that first
project I mentioned was an argument about something that was not part of
the primary purpose of the project which exploded with a fury resembling
a religious confrontation. I do not want to see that happen to Git. I
didn't want to see that project die either, but when you exasperate
enough of the core developers that's what happens. 

(My first job as project leader was to get it off of our CVS host, the
second was to find it a nice grave over at nongnu.org. I never did get
CVS import to work. I never did convince any of the core developers that
it was still worth working on.)

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

[1.8.0] Re: reorganize the mess that the source tree has become

[Nicolas Sebrecht]

The 04/02/11, Drew Northup wrote:

> Having once upon a time (in CVS days) taken over a project that was
> neatly organized into tons of folders I can say that more folders is not
> always better.
> If you are organizing things into modules by folders, and those things
> are mutually exclusive pre-compilation then doing so may make sense. If
> the folders ADD value to the project by adding organization--as opposed
> to hiding disorganization--then they may have value.

This _is_ what we are talking about. Not tons of folders or whathever
you might think.

> destructive things
>                                                       killed that first
> project
>                            project       exploded with a fury resembling
> a religious confrontation.                  see that happen to Git
>                see that project die                  you exasperate
> enough of the core developers

Read again. I'm pretty sure this was not your goal but this almostly
looks like FUD to me. So, I don't think I'll involve to more discussion
in this subthread.

-- 
Nicolas Sebrecht