You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@subversion.apache.org by Gary Feldman <g1...@marsdome.com> on 2004/05/28 18:02:54 UTC
Comments on the book
I had hoped to have the time to provide some more extensive comments, but
unfortunately paying work had to take priority. But here are some initial
reactions, along with one nit. I've placed the more objective points first,
with the more opinionated stuff later.
The nit first, because it's trivial. In Chapter 1, A Quick Start, there's
an example that shows
$ ls /path/to/repos
conf/ dav/ db/ ....
It should be ls -F, because standard ls doens't show the trailing / on
directories. True, many people may have it aliased that way, sometimes
without even being aware of it, but it's better to be precise.
More general structural comments (way too late, but perhaps the next
edition):
1. The HTML version, at least, often says "see the section called ...." I
really hope that it doesn't appear that way in the print edition. It looks
like an artifact of the software that processed the book sources, but it's
really bad.
2. The Subversion's Components section in chapter one lists several items,
such as svnversion and svndumpfilter that don't show up in The Complete
Reference chapter. Indeed, snversion doesn't seem to show up anywhere else,
while the svndumpfilter reference info, and some others, is in the
Repository Administration chapter. It's not that I want to take "Complete
Reference" overly literally, but that I think such information really does
belong together in the reference. (In other words, you can't fix this by
deleting the word "Complete" from the title of Chapter 9.)
3. There are a number of places where you do a very good job of presenting
alternative approaches diplomatically, but the Lock-Modify-Unlock vs
Copy-Modify-Merge model isn't one of them. This is going to look silly,
given that locking is the very first item on the post-1.0 list. But even
worse, you don't really do justice to the discussion, nor should you. I
know from reading this list that you're familiar with many of the issues and
approaches that underly these two approaches, but that doesn't show up in th
is part of the book. The end result, I fear, is that anyone familiar with
concepts such as advisory locks, or with good experience using locking
models (i.e. ClearCase, whose popularity belies the strong criticism of the
locking model), will simply read this section, decide you're not as familiar
with the subject as I know you are, and disgard the book and subversion.
But there's no reason for you to even get into this discussion. This is a
book about subversion, not about version control systems in general. The
fact that the copy-modify-merge model is popular is all the justification
you need here. Just don't raise the issue at all.
4. I really hate the overuse of the term "use-case" in the manual. The
term is being overused everywhere, to the point of becoming a fad that
dilutes and obscures its original meaning.
Use-cases are a requirements technique. They are applied before defining
the user interface or designing the product. As such, they're written
before things such as command line syntax come into existence, and are far
more abstract than what you have. True, they're a good place to start for
writing user documents, but the label doesn't come over (just like you can
use BNF as a basis for a reference manual, but you can't describe the
reference as a formal syntax). What you have can, at best, be described as
the way subversion solves particular use-case problems.
But please, stop using the term altogether. The more people keep using the
term outside of a requirements process, the less valuable it becomes, and
we'll be back where we were fifteen years ago, when requirements engineering
was an obscure part of software engineering that few developers understood
or cared about. (I like Ambler's brief paper at
http://www-106.ibm.com/developerworks/webservices/library/ws-tip-docusecase.html
as a good online description of use-cases, but there are many others.)
Regards, keep up the good work, and notwithstanding these comments, I hope
the book sells well,
Gary
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Comments on the book
Posted by Ben Collins-Sussman <su...@collab.net>.
On Tue, 2004-06-01 at 21:30, Gary Feldman wrote:
> > It's been exceedingly useful. A boss doesn't
> > want to hear that "copy-modify-merge is popular", they need to be told
> > why universal lock-modify-lock policies are harmful too.
>
> Why? What does that have to do with a Subversion User's Guide? I'll
> rephrase what I said earlier: The primary purpose of the book is how to use
> Subversion, not which methodology is better (or even how to do SCM).
Not true. The book is not a man page. It's not just "how to use a
tool." It's about "how the tool works, the philosophy behind its
design, why we think the philosophy is better than the alternative, and
how to use this philosophy to accomplish a certain type of SCM."
The audience is more than people merely looking to use a tool in a
vaccuum. If we simply said, "we use copy-modify-merge, end of story",
many readers would come to this list and say, "But *why*? I've only
ever used locking systems. Why this other weird model? Why did you
choose it?"
I don't see the utility in making the book strive for perfect
objectivity. As you said, that's a goal for a comparative research
paper on SCM strategies. The book, on the other hand, strives to get
people comfortable with just one system, and to do that effectively it
must hand out just a bit of one-sided Kool-Aid. There's no horrible
shame in that.
> I can think of several situations where it should be, but in most
> situations, it doesn't matter. There are much more significant criteria.
Granted, SCM models aren't my area of expertise. But I'd love to hear
someone argue a strong case for lock-modify-unlock. I'd love to hear a
one-sided argument for the other side. :-)
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Comments on the book
Posted by Gary Feldman <g1...@marsdome.com>.
>From: "Ben Collins-Sussman" <su...@collab.net>
>Sent: Saturday, May 29, 2004 9:30 AM
> I respectfully disagree. A vast number of readers have experience with
> version control, specifically with systems like Visual Source Safe. For
> this audience, copy-modify-merge is a new idea, and it's deliberately
> compared to lock-modify-lock because readers *are* familiar with the
> latter model already.
I'm not suggesting you avoid discussing how copy-modify-merge works, or even
what its benefits are. I'm suggesting that the comparison (i.e. debate)
over which is better belongs in a white paper, not the book.
> It's been exceedingly useful. A boss doesn't
> want to hear that "copy-modify-merge is popular", they need to be told
> why universal lock-modify-lock policies are harmful too.
Why? What does that have to do with a Subversion User's Guide? I'll
rephrase what I said earlier: The primary purpose of the book is how to use
Subversion, not which methodology is better (or even how to do SCM).
The problem is that you don't make a credible case in the book. Maybe there
are some pointy-haired bosses whose mental process is "If it's in print, it
much be true." I've been lucky with regard to bosses, because on the one
hand, they listen to my opinion with an open mind, and on the other hand,
they're not easily swayed by one-sided arguments. And anyone with
significant experience with SCM will quickly identify the discussion in the
book as one-sided.
> ... it should never be the default mode of
> behavior.
I can think of several situations where it should be, but in most
situations, it doesn't matter. There are much more significant criteria.
Gary
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Comments on the book
Posted by Adrian Howard <ad...@quietstars.com>.
On 3 Jun 2004, at 17:28, Daragh Fitzpatrick wrote:
>> I can't tell you how many times that section of the book has been
>> shown to pointy-haired-bosses who freak at the concept of copy-
>> modify-merge. It's been exceedingly useful. A boss doesn't
>> want to hear that "copy-modify-merge is popular", they need to be
>> told why universal lock-modify-lock policies are harmful too.
>
> Having just gone through this, I would like to heartily agree. Thanks!
[snip]
Ditto. While I've not done it recently I have done it more than once.
With developers as well as PHBs.
A very useful section. A thank you to whoever wrote it.
Cheers,
Adrian
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
RE: Comments on the book
Posted by Daragh Fitzpatrick <Da...@UChicago.edu>.
> I can't tell you how many times that section of the book has been
> shown to pointy-haired-bosses who freak at the concept of copy-
> modify-merge. It's been exceedingly useful. A boss doesn't
> want to hear that "copy-modify-merge is popular", they need to be
> told why universal lock-modify-lock policies are harmful too.
Having just gone through this, I would like to heartily agree. Thanks!
Cheers,
:D
--------------------------------------------------------------------
Daragh Fitzpatrick Daragh@UChicago.edu (773) 702-8976
Solutions Architect NSIT Administrative Systems
Renewal Projects and Architecture University of Chicago
--------------------------------------------------------------------
-----Original Message-----
From: Mark Phippard [mailto:MarkP@softlanding.com]
Sent: Saturday, May 29, 2004 9:24 AM
To: users@subversion.tigris.org
Subject: Re: Comments on the book
Ben Collins-Sussman <su...@collab.net> wrote on 05/29/2004 09:30:12 AM:
> Gary Feldman wrote:
>
> > But there's no reason for you to even get into this discussion.
> > This
is a
> > book about subversion, not about version control systems in general.
The
> > fact that the copy-modify-merge model is popular is all the
justification
> > you need here. Just don't raise the issue at all.
>
> I respectfully disagree. A vast number of readers have experience
> with version control, specifically with systems like Visual Source
> Safe. For
> this audience, copy-modify-merge is a new idea, and it's deliberately
> compared to lock-modify-lock because readers *are* familiar with the
> latter model already. I can't tell you how many times that section of
> the book has been shown to pointy-haired-bosses who freak at the
> concept
> of copy-modify-merge. It's been exceedingly useful. A boss doesn't
> want to hear that "copy-modify-merge is popular", they need to be told
> why universal lock-modify-lock policies are harmful too.
>
> When the book is updated for 1.1, we can tone it down a bit. Locking
> *is* useful for certain situations (such as preventing wasted time
> editing unmergeable files), but it should never be the default mode of
> behavior.
>
I agree. Having that chapter in there is very useful in the corporate
world. A lot of people have the idea that you are not doing "real"
version control if you do not have locks, so it is nice to have a well
written explanation of the philosophies and why copy-modify-merge works
better. I think the chapter will only get better when it acknowledges
that there are situations where locks are needed.
I had always worked in the "locks" world and thought it was better than
the CVS model. I have been doing a lot of J2EE development lately and it
would be virtually impossible to do in a locking version control system as
there are so many XML files that EVERYONE has to be able to edit and
modify to do any work. If the file was always locked no one could ever do
anything.
Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Comments on the book
Posted by Mark Phippard <Ma...@softlanding.com>.
Ben Collins-Sussman <su...@collab.net> wrote on 05/29/2004 09:30:12 AM:
> Gary Feldman wrote:
>
> > But there's no reason for you to even get into this discussion. This
is a
> > book about subversion, not about version control systems in general.
The
> > fact that the copy-modify-merge model is popular is all the
justification
> > you need here. Just don't raise the issue at all.
>
> I respectfully disagree. A vast number of readers have experience with
> version control, specifically with systems like Visual Source Safe. For
> this audience, copy-modify-merge is a new idea, and it's deliberately
> compared to lock-modify-lock because readers *are* familiar with the
> latter model already. I can't tell you how many times that section of
> the book has been shown to pointy-haired-bosses who freak at the concept
> of copy-modify-merge. It's been exceedingly useful. A boss doesn't
> want to hear that "copy-modify-merge is popular", they need to be told
> why universal lock-modify-lock policies are harmful too.
>
> When the book is updated for 1.1, we can tone it down a bit. Locking
> *is* useful for certain situations (such as preventing wasted time
> editing unmergeable files), but it should never be the default mode of
> behavior.
>
I agree. Having that chapter in there is very useful in the corporate
world. A lot of people have the idea that you are not doing "real"
version control if you do not have locks, so it is nice to have a well
written explanation of the philosophies and why copy-modify-merge works
better. I think the chapter will only get better when it acknowledges
that there are situations where locks are needed.
I had always worked in the "locks" world and thought it was better than
the CVS model. I have been doing a lot of J2EE development lately and it
would be virtually impossible to do in a locking version control system as
there are so many XML files that EVERYONE has to be able to edit and
modify to do any work. If the file was always locked no one could ever do
anything.
Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: Comments on the book
Posted by Ben Collins-Sussman <su...@collab.net>.
Gary Feldman wrote:
> But there's no reason for you to even get into this discussion. This is a
> book about subversion, not about version control systems in general. The
> fact that the copy-modify-merge model is popular is all the justification
> you need here. Just don't raise the issue at all.
I respectfully disagree. A vast number of readers have experience with
version control, specifically with systems like Visual Source Safe. For
this audience, copy-modify-merge is a new idea, and it's deliberately
compared to lock-modify-lock because readers *are* familiar with the
latter model already. I can't tell you how many times that section of
the book has been shown to pointy-haired-bosses who freak at the concept
of copy-modify-merge. It's been exceedingly useful. A boss doesn't
want to hear that "copy-modify-merge is popular", they need to be told
why universal lock-modify-lock policies are harmful too.
When the book is updated for 1.1, we can tone it down a bit. Locking
*is* useful for certain situations (such as preventing wasted time
editing unmergeable files), but it should never be the default mode of
behavior.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org