one more example of unclear terminology in SVN book

["Robert P. J. Day" <rp...@mindspring.com>]

on p. 23 (PDF version), section "Initial Checkout", here's a perfect
example of vague terminology:

"Most of the time, you will start using a Subversion repository by
doing a checkout of your project. Checking out a repository creates a
copy of it on your local machine. This copy contains the HEAD (latest
revision) of the Subversion repository that you specify on the command
line:

  $ svn checkout http://svn.collab.net/repos/svn/trunk"

  in the space of just a few lines, there are at least two thoroughly
confusing uses of terminology.

  first, are we doing a "checkout of your project" or are we "Checking
out a repository"?  does a repo contain one project, or possibly
multiple projects?

  and as for the actual checkout command:

  $ svn checkout http://svn.collab.net/repos/svn/trunk

what part of that URL represents the "repository" itself?  the text
clearly refers to the "Subversion repository that you specify on the
command line".  but from earlier, one would have concluded that the
repo is represented by just "http://svn.collab.net/repos".  after all,
that was the argument to the "svnadmin create" command.

  but now, it appears to be "http://svn.collab.net/repos/svn/trunk".
so which one represents the repository?  and which one the project?
or what?

rday

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org

Re: one more example of unclear terminology in SVN book

["Robert P. J. Day" <rp...@mindspring.com>]

On Sun, 19 Dec 2004, Ben Collins-Sussman wrote:

> Hm, okay.  Perhaps we should exise the word 'project' from all of
> the early chapters.  Subversion has no concept of 'project' at all,
> just directories. Perhaps we should just standardize on the phrase
> "check out part of a repository".

actually, having whined about this, i'm not sure you really need to
delete the word "project" entirely, so much as emphasize early on that
it's strictly an informal term that is commonly applied to, say,
top-level directories in a repository that folks might find it useful
to check out independently.  kind of a loose, shortcut terminology,
but having *no* official meaning in the context of svn.

and, personally, i think it would have been handy to have seen
something like Figure 4.2 earlier, showing the calc and paint
directories with their own "trunk/" and "branches/" subdirectories.
*that* picture goes a long way to graphically depicting how to break a
repo into separate (dare i use the word?) "projects".  :-)

rday

p.s.  based on what i've seen so far, i'm assuming you can introduce
the trunk/tags/branches at any arbitrary subdirectory level where you
think folks might want to be creating branches and doing tagging, yes?

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org

Re: one more example of unclear terminology in SVN book

[Ben Collins-Sussman <su...@collab.net>]

On Dec 19, 2004, at 1:55 PM, Robert P. J. Day wrote:

> On Sun, 19 Dec 2004, Ben Collins-Sussman wrote:
>
>>
>> On Dec 19, 2004, at 11:16 AM, Robert P. J. Day wrote:
>>>
>>>   first, are we doing a "checkout of your project" or are we 
>>> "Checking
>>> out a repository"?  does a repo contain one project, or possibly
>>> multiple projects?
>>
>> Chapter 3 is written for users trying to learn the commandline
>> client, and it assumes an administrator has already "set up" a
>> project for them to check out. It's not important whether there are
>> N projects in 1 repository, or N separate repositories.  It's not
>> important what part of the URL represents the repository itself.
>> These issues are only important to administrators setting things up.
>>
>> All that matters is that an administrator has given the user a URL
>> to "check out", and that's what this chapter is assuming.  Perhaps
>> chapter 3 should state that explicitly?  Would that make things
>> clearer?
>
> even for a simple example like this, i still think it's critically
> important to use terminology consistently.  should the beginning user
> think he's checking out a repository?  or a project in a repository?
> yes, there's a difference.  you initialize a repo with "svnadmin
> create".  you don't do the same for a "project", so to constantly
> interchange the two words is, fer shure, going to confuse at least a
> few people.
>

Hm, okay.  Perhaps we should exise the word 'project' from all of the 
early chapters.  Subversion has no concept of 'project' at all, just 
directories.  Perhaps we should just standardize on the phrase "check 
out part of a repository".

Thanks for the feedback!


---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org

Re: one more example of unclear terminology in SVN book

["Robert P. J. Day" <rp...@mindspring.com>]

On Sun, 19 Dec 2004, Ben Collins-Sussman wrote:

>
> On Dec 19, 2004, at 11:16 AM, Robert P. J. Day wrote:
> >
> >   first, are we doing a "checkout of your project" or are we "Checking
> > out a repository"?  does a repo contain one project, or possibly
> > multiple projects?
>
> Chapter 3 is written for users trying to learn the commandline
> client, and it assumes an administrator has already "set up" a
> project for them to check out. It's not important whether there are
> N projects in 1 repository, or N separate repositories.  It's not
> important what part of the URL represents the repository itself.
> These issues are only important to administrators setting things up.
>
> All that matters is that an administrator has given the user a URL
> to "check out", and that's what this chapter is assuming.  Perhaps
> chapter 3 should state that explicitly?  Would that make things
> clearer?

even for a simple example like this, i still think it's critically
important to use terminology consistently.  should the beginning user
think he's checking out a repository?  or a project in a repository?
yes, there's a difference.  you initialize a repo with "svnadmin
create".  you don't do the same for a "project", so to constantly
interchange the two words is, fer shure, going to confuse at least a
few people.

rday

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org

Re: one more example of unclear terminology in SVN book

[Ben Collins-Sussman <su...@collab.net>]

On Dec 19, 2004, at 11:16 AM, Robert P. J. Day wrote:
>
>   first, are we doing a "checkout of your project" or are we "Checking
> out a repository"?  does a repo contain one project, or possibly
> multiple projects?

Chapter 3 is written for users trying to learn the commandline client, 
and it assumes an administrator has already "set up" a project for them 
to check out.  It's not important whether there are N projects in 1 
repository, or N separate repositories.  It's not important what part 
of the URL represents the repository itself.  These issues are only 
important to administrators setting things up.

All that matters is that an administrator has given the user a URL to 
"check out", and that's what this chapter is assuming.  Perhaps chapter 
3 should state that explicitly?  Would that make things clearer?


---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org

Re: one more example of unclear terminology in SVN book

["Robert P. J. Day" <rp...@mindspring.com>]

On Mon, 20 Dec 2004, Ryan Schmidt wrote:

> Perhaps it's also a bit confusing for the newcomer that the SVN book
> here uses "svn" as the name of an example project. When I set up my
> repository, it might not come as too much of a surprise that I named
> the directory "svn" ...

that threw me the first time i read it as well.  given that the
subversion per-directory admin dirname is ".svn", i just naturally
assumed there was something magic about the name "svn" as well at that
location.

more generally, i think it's important to always label examples with
which parts have required, mandated names, and which names are
user-chosen and arbitrary.  when it comes down to it, even the
directory names "trunk", "branches" and "tags" are flexible -- someone
else might choose to call them "main", "br" and "tg" for all i know.
not that i'd encourage that sort of thing, but it's stull useful to
know that those names aren't fixed in stone.

rday

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org

Re: one more example of unclear terminology in SVN book

[Ryan Schmidt <su...@ryandesign.com>]

On 19. Dez 2004, at 18:16, Robert P. J. Day wrote:

> on p. 23 (PDF version), section "Initial Checkout", here's a perfect
> example of vague terminology:
>
> "Most of the time, you will start using a Subversion repository by
> doing a checkout of your project. Checking out a repository creates a
> copy of it on your local machine. This copy contains the HEAD (latest
> revision) of the Subversion repository that you specify on the command
> line:
>
> $ svn checkout http://svn.collab.net/repos/svn/trunk"
>
> in the space of just a few lines, there are at least two thoroughly
> confusing uses of terminology.
>
> first, are we doing a "checkout of your project" or are we "Checking
> out a repository"?  does a repo contain one project, or possibly
> multiple projects?

I agree that here, two words which mean different things ("repository" 
and "project") are used as if they are interchangeable, and that this 
is particularly confusing for someone like me, coming to SVN with no 
previous background in version control. I'd appreciate very clear and 
deliberate use of terms in the documentation to solidify my 
understanding of them.

Perhaps it's also a bit confusing for the newcomer that the SVN book 
here uses "svn" as the name of an example project. When I set up my 
repository, it might not come as too much of a surprise that I named 
the directory "svn" so now when I read such examples it takes me a 
minute to figure out that "svn" in the example is not the repository 
but a project within it. It would have reduced my confusion if a name 
like "sampleproject" had been used. I realize that this specific 
example was probably trying to give a real working example, so I'm not 
sure how to meet that goal and also implement my suggestion.



---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org