[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: [PATCH] clarification for ch02 of book

From: Mason Thomas <mlt_svn_at_sbcglobal.net>
Date: 2003-01-05 07:43:13 CET

This may have been lost in the holiday shuffle...

I did not correctly close some tags. I also found a typo and a couple
other minor changes. Please look at the following patch instead of the
original one.

I also forgot a log:
* doc/book/book/ch02.xml
 minor text tweaks (mainly regarding locking)

-Mason

Ben Collins-Sussman wrote:

> Thanks, I'll take a look at this over the holiday!
>
> Mason Thomas <mlt_svn@sbcglobal.net> writes:
>
>
>
>> Hi,
>> the following is a resend.
>>
>> The following patch is a suggested change for ch02.xml (chapter 2 of
>> S:TDG). The patch itself is just suggested text, but the intent, I
>> think, is important. That intent is to clarify the failings of a
>> lock-based version control system.
>>
>> The first change may reflect my misunderstanding of locking versioning
>> systems. As it stands ("All she can do is read the file...") the text
>> implies that Jane can read the file but just not obtain a lock for
>> editing. But what is to stop her from reading the file, waiting till
>> she can acquire a lock, then editing the (out-of-date) version she
>> has? My suggested change implies she cannot even read the file, but
>> that may be wrong. Either way, the current text appears to suggest
>> that locking doesn't prevent out-of-date problems from occurring.
>>
>> The remaining changes add mini-headings to the list of problems with
>> the lock-modify-unlock model. I think this helps to make the failings
>> more memorable and/or explicit to the reader. I used <emphasis> tags,
>> but something else might be more appropriate.
>>
>> -Mason
>>
>> <original patch snipped>
>>
>>
>
Index: ch02.xml
===================================================================
--- ch02.xml (revision 4186)
+++ ch02.xml (working copy)
@@ -110,10 +110,10 @@
        making changes to it. Locking a file is a lot like borrowing
        a book from the library; if Joe has locked a file, then Jane
        cannot make any changes to it. If she tries to lock the file,
- the repository will deny the request. All she can do is read
- the file, and wait for Joe to finish his changes and release
- his lock. After Joe unlocks the file, his turn is over, and
- now Jane can take her turn by locking and editing.</para>
+ the repository will deny the request. All she can do is wait
+ for Joe to finish his changes and release his lock. After Joe
+ unlocks the file, his turn is over, and now Jane can take her
+ turn by locking and editing.</para>

      <figure id="svn-ch2-dia3">
        <title>The lock-modify-unlock solution</title>
@@ -125,14 +125,18 @@
        users:</para>

      <itemizedlist>
- <listitem><para>Sometimes Joe will lock a file and then forget
+ <listitem><para><emphasis>Locking may cause administrative
+ difficulties.</emphasis>
+ Sometimes Joe will lock a file and then forget
            about it. Meanwhile, because Jane is still waiting to
            edit the file, her hands are tied. And then Joe goes on
            vacation. Now Jane has to get an administrator to release
            Joe's lock. The situation ends up causing a lot of
            unnecessary delay and wasted time.</para></listitem>

- <listitem><para>What if Joe is editing the beginning of a text
+ <listitem><para><emphasis>Locking may unnecessarily slow
+ file editing.</emphasis>
+ What if Joe is editing the beginning of a text
            file, and Jane simply wants to edit the end of the same
            file? These changes don't overlap at all. They could
            easily edit the file simultaneously, and no great harm
@@ -140,13 +144,15 @@
            together. There's no need for them to take turns in this
            situation.</para></listitem>

- <listitem><para>Pretend that Joe locks and edits file A, while
+ <listitem><para><emphasis>Locking does not prevent all conflicts.
+ </emphasis>
+ Pretend that Joe locks and edits file A, while
            Jane simultaneously locks and edits file B. But suppose
            that A and B depend on one another, and the changes made
            to each are semantically incompatible. Suddenly A and B
            don't work together anymore, and the locking system was
            powerless to prevent it&mdash;yet the locking system somehow
- provided a sense of false security, when it shouldn't
+ provided a false sense of security, when it shouldn't
            have.</para></listitem>
      </itemizedlist>

@@ -286,7 +292,7 @@
        out</firstterm> some subtree of the repository. (The term
        "check out" may sound like it has something to do with locking
        or reserving resources, but it doesn't; it simply creates a
- private copy of the project for you.) For example, If you
+ private copy of the project for you.) For example, if you
        check out <filename>/calc</filename>, you will get a working
        copy like this: </para>

@@ -313,7 +319,7 @@
        tell that you've changed the file. However, Subversion does
        not make your changes public until you explicitly tell it to.
        The act of publishing your changes is more commonly known as
- <firstterm>committing</firstterm> or (<firstterm>checking
+ <firstterm>committing</firstterm> (or <firstterm>checking
        in</firstterm>) changes to the repository.</para>

      <para>To publish your changes to others, you can use
@@ -386,7 +392,7 @@
      <para>Each time the repository accepts a commit, this creates a
        new state of the filesystem tree, called a
        <firstterm>revision</firstterm>. Each revision is assigned a
- unique natural number, one greater than the number of the
+ unique serial number, one greater than the number of the
        previous revision. The initial revision of a freshly created
        repository is numbered zero, and consists of nothing but an
        empty root directory.</para>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Jan 5 07:42:51 2003

This is an archived mail posted to the Subversion Dev mailing list.