You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Chris Pepper <pe...@reppep.com> on 2004/10/02 04:32:34 UTC
[BOOK] [PATCH] Niggles in Chapter 3
"specify a date by specifying the date" is redundant.
As written, .svn sounds like a read-only area; the injunction
is really against direct manipulation.
"This places your working copy into" is awkward. I believe
"This places your working copy in" is more correct, but am not
certain.
The most important thing about svn add is that it adds, not
that it's deferred.
>- changes coming from the repository didn't overlap in any
>- way.</para>
>+ changes coming from the repository didn't overlap.</para>
But of course, Subversion can't guarantee there's no
(semantic) overlap. Tone it down to what can be guaranteed. Even
better, specify in the text that the test used is for changes which
affect the same line, or whatever svn uses internally.
Rephrase active use of "log" (which implies adding/editing
the log) to passive use (for reviewing existing log entries).
The final change is for a complicated sentence with three
parts, which as written implied all three parts (including the
transaction itself and discarding the log) take place before the
transaction. I have tried to disentangle it with minimal revision.
Alternatively, change:
Before changing anything it writes its intentions to a log file, then
executes the commands in the log file, and finally removes the log
file (this is similar in design to a journaled filesystem).
to:
Before changing the repository, Subversion writes its intentions to a
log file. Next it executes the commands in the log file to apply the
requested change. Finally, Subversion removes the log file.
Architecturally, this is similar to a journaled filesystem).
Chris Pepper
Index: ch03.xml
===================================================================
--- ch03.xml (revision 11198)
+++ ch03.xml (working copy)
@@ -201,7 +201,7 @@
<title>Revision Dates</title>
<para>Anywhere that you specify a revision number or revision
- keyword, you can also specify a date by specifying the date
+ keyword, you can also specify a date
inside curly braces <quote>{}</quote>. You can even access
a range of changes in the repository using both dates and
revisions together!</para>
@@ -370,7 +370,7 @@
<filename>.svn</filename>. Usually, directory listing
commands won't show this subdirectory, but it is nevertheless
an important directory. Whatever you do, don't delete or
- change anything in the administrative area! Subversion
+ change anything in the administrative area directly! Subversion
depends on it to manage your working copy.</para>
</sidebar>
@@ -378,7 +378,7 @@
<para>While you can certainly check out a working copy with the
URL of the repository as the only argument, you can also specify
a directory after your repository URL. This places your working
- copy into the new directory that you name. For example:</para>
+ copy in the new directory that you name. For example:</para>
<screen>
$ svn checkout http://svn.collab.net/repos/svn/trunk subv
@@ -636,7 +636,7 @@
become a child of its parent directory. Note that if
<filename>foo</filename> is a directory, everything
underneath <filename>foo</filename> will be scheduled
- for addition. If you only want to schedule
+ for addition. If you only want to add
<filename>foo</filename> itself, pass the
<option>--non-recursive</option> (<option>-N</option>)
switch.</para>
@@ -917,7 +917,7 @@
might have a file in the repository, but you removed
the file and created a directory in its place, without
using the <command>svn delete</command> or
- <command>svn add</command> commands.</para>
+ <command>svn add</command> command.</para>
</listitem>
</varlistentry>
@@ -1259,8 +1259,7 @@
from the repository. The <computeroutput>G</computeroutput>
stands for mer<computeroutput>G</computeroutput>ed, which
means that the file had local changes to begin with, but the
- changes coming from the repository didn't overlap in any
- way.</para>
+ changes coming from the repository didn't overlap.</para>
<para>But the <computeroutput>C</computeroutput> stands for
conflict. This means that the changes from the server overlapped
@@ -1703,7 +1702,7 @@
<sect2 id="svn-ch-3-sect-5.1">
<title><command>svn log</command></title>
- <para>To find out information about the history of a file or
+ <para>To find information about the history of a file or
directory, use the <command>svn log</command>
command. <command>svn log</command> will provide you with a
record of who made changes to a file or directory, at what
@@ -1799,12 +1798,12 @@
supply no path, Subversion uses the current working
directory as the default target. As a result, if you're
operating in a subdirectory of your working copy and attempt
- to log a revision in which neither that directory nor any of
- its children was changed, Subversion will give you an empty
- log. If you want to see what changed in that revision, try
- pointing <command>svn log</command> directly at the top-most
- URL of your repository, as in <command>svn log -r 2
- http://svn.collab.net/repos/svn</command>.</para>
+ to see the log of a revision in which neither that directory
+ nor any of its children was changed, Subversion will show you
+ an empty log. If you want to see what changed in that
+ revision, try pointing <command>svn log</command> directly at
+ the top-most URL of your repository, as in <command>svn log -r
+ 2 http://svn.collab.net/repos/svn</command>.</para>
</sidebar>
@@ -2047,9 +2046,9 @@
<para>When Subversion modifies your working copy (or any
information within <filename>.svn</filename>), it tries to do
- so as safely as possible. Before changing anything, it writes
- its intentions to a log file, executes the commands in the log
- file, then removes the log file (this is similar in design to
+ so as safely as possible. Before changing anything it writes
+ its intentions to a log file, then executes the commands in the log
+ file, and finally removes the log file (this is similar in design to
a journaled filesystem). If a Subversion operation is
interrupted (if the process is killed, or if the machine
crashes, for example), the log files remain on disk. By
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Putting log messages with patch submissions [was: [BOOK] [PATCH]
Niggles in Chapter 3]
Posted by Julian Foad <ju...@btopenworld.com>.
Simon Large wrote:
> The HACKING document specifies that patches should be in unified-diff format
> and that they should have a log message in a particular format. It does not
> state how the log message should be included in the patch.
The log message should be readable in the e-mail, which means it should either be in-line text or, if the patch is attached with a MIME type like "text/plain" so that it is readable in most e-mail programs, the log message can be prefixed to the patch file.
> Looking through the dev list, log messages seem to be prefixed to the
> unified-diff and enclosed triple square brackets:
>
> [[[
> Log message lines...
> ]]]
>
> Is this an unwritten standard, a GNU standard, or something
> else? Is the preferred patch format documented anywhere?
I regard that as an ad-hoc standard for quoting blocks of text, and thus a reasonable way of marking a log message within an e-mail message. It's just something I saw somewhere and started doing here.
Sometimes the extent of a log message is easily recognisable even without markers delimiting it. A committer will always have to cut and paste the log message, review it, and often "tweak" it, so we don't need a rigid, automatable standard for this.
> The reason for the question is that I want to propose some changes to TSVN
> to make patches easier to create and apply. Obviously if there is an
> existing standard then it should be used.
I don't know whether the TSVN project wants patches submitted in the same style that the Subversion project does, but it seems like a reasonable starting point.
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [BOOK] [PATCH] Niggles in Chapter 3
Posted by Simon Large <sl...@blazepoint.co.uk>.
"Julian Foad" wrote
> Please could you read the file "HACKING" in the root directory,
> at least the parts of it that describe submitting a patch.
> In particular, it would be helpful if you could format your
> log message in the required way.
No-one responded to this on the user list, but it is kind of related to this
thread.
The HACKING document specifies that patches should be in unified-diff format
and that they should have a log message in a particular format. It does not
state how the log message should be included in the patch.
Looking through the dev list, log messages seem to be prefixed to the
unified-diff and enclosed triple square brackets:
[[[
Log message lines...
]]]
Is this an unwritten standard, a GNU standard, or something
else? Is the preferred patch format documented anywhere?
The reason for the question is that I want to propose some changes to TSVN
to make patches easier to create and apply. Obviously if there is an
existing standard then it should be used.
Simon
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [BOOK] [PATCH] Niggles in Chapter 3
Posted by Julian Foad <ju...@btopenworld.com>.
Chris Pepper wrote:
> At 9:13 PM +0100 2004/10/03, Julian Foad wrote:
>> I left out the removal of spaces before </para> because it only
>> covered a few of them, [...]
>
> Your ' </para> scan didn't pick up </para> on lines by itself, did
> it? I thought I checked and caught all the other cases, but didn't pay
> much attention at the time.
It didn't. Anyway, I've done them now.
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [BOOK] [PATCH] Niggles in Chapter 3
Posted by Chris Pepper <pe...@reppep.com>.
At 9:13 PM +0100 2004/10/03, Julian Foad wrote:
>Julian Foad wrote:
>>[...] could you try to save and open it as a simple file of plain
>>text. Sorry for the hassle (yes, I know, things like this are just
>>supposed to work, but ...).
>
>Chris, rather than make you submit it again, I have just committed
>nearly all of your patch in r11214.
>
>I left out the removal of spaces before </para> because it only
>covered a few of them, and I removed the unmatched parenthesis, and
>I used my wording "valid only for local repositories", and I wrapped
>a couple of words onto an adjacent line to reduce the number of
>lines changed by the patch.
>
>I hope that's OK with you.
Sounds good, thanks. I have a query in about getting Eudora
to send text/plain or something else suitable. I could send patches
via SquirrelMail, I suppose, which probably uses the right MIME type
if Eudora can't be made to DTRT for Subversion patches.
Your ' </para> scan didn't pick up </para> on lines by
itself, did it? I thought I checked and caught all the other cases,
but didn't pay much attention at the time.
Chris
--
Chris Pepper: <http://www.reppep.com/~pepper/>
Rockefeller University: <http://www.rockefeller.edu/>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [BOOK] [PATCH] Niggles in Chapter 3
Posted by Julian Foad <ju...@btopenworld.com>.
Julian Foad wrote:
> [...] could you try to save and open it as a simple file of
> plain text. Sorry for the hassle (yes, I know, things like this are
> just supposed to work, but ...).
Chris, rather than make you submit it again, I have just committed nearly all of your patch in r11214.
I left out the removal of spaces before </para> because it only covered a few of them, and I removed the unmatched parenthesis, and I used my wording "valid only for local repositories", and I wrapped a couple of words onto an adjacent line to reduce the number of lines changed by the patch.
I hope that's OK with you.
Thanks for the patch.
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [BOOK] [PATCH] Niggles in Chapter 3
Posted by Julian Foad <ju...@btopenworld.com>.
Julian Foad wrote:
> I see that you've now read the bit about attaching a patch to the
> e-mail; unfortunately you have (or your software has) given it the MIME
> type "multipart/appledouble" which my mail program has never heard of.
If you can't resolve that, it's not a disaster: we can still receive your patches, just not so easily. Don't let this get in the way of continuing your good work.
Also, if you have the ability to run a Bash shell script in a Unix-like environment, you might find my book anomaly checking script useful (separate thread: "BOOK: a heuristic anomaly-detection script"). Your patch prompted me to add a few more checks to it, including space before </para> (and it finds several more of those), and to post it to the list.
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [BOOK] [PATCH] Niggles in Chapter 3
Posted by Julian Foad <ju...@btopenworld.com>.
Chris Pepper wrote:
>
> Sorry, I read doc/book/HACKING, not /HACKING. I was concerned that
That's OK. Thanks for reading up and re-submitting so soon.
I see that you've now read the bit about attaching a patch to the e-mail; unfortunately you have (or your software has) given it the MIME type "multipart/appledouble" which my mail program has never heard of. If you could attach it as type "text/plain" or "text/x-diff" or "text/x-patch" that would allow me to see it much more easily. If your mail program doesn't give you an option, then it probably chooses a type based on how you saved the file or how you opened the file for attaching, so could you try to save and open it as a simple file of plain text. Sorry for the hassle (yes, I know, things like this are just supposed to work, but ...).
I was able to save the attachment to disk and then read it - it seems to be just plain text inside.
> some of the language nits were subtle enough to require explanation; per
> your suggestion, I've removed those explanations from the below.
It was useful to have the full explanations in your e-mail; it would also be OK to have them in the log message but I felt that it was less necessary to have them there since, by that time, at least two of us will have agreed that they make sense.
> I guessed at the desired level of verbosity for language cleanup
> (not mentioning most of the miscellaneous language tweaks). If more
> detail is required, please let me know, ideally with a sample log
> message illustrating the right level of detail.
That's about right. A little more detail would be OK, and a little less would also be OK.
> Remove spaces around '—' to conform with the style guide. (Note:
> I didn't actually find this spelled out, but Julian Foad confirms the
> preferred style.)
Eek - it's nothing to do with me, gov'nor! I can't find where it says so, either, but it has been stated many times on this e-mail list. (If I commit this patch to the repository then it will implicitly have been approved by me so we won't need this note.)
Comments on the patch itself:
After the phrase "journaled filesystem" you have left an unmatched parenthesis.
"Remember that the 'file:' access method is valid only for locations on the same server as the client" ->
"Remember that the 'file:' access method is valid only for locations on the client"
I'm not sure about this. I agree that the original text sounds silly, but I think your replacement is also odd. "The client" in this context would refer to a Subversion client program. Strictly speaking, this needs to talk about the file system that is (logically) local to the program that is using the 'file:' URL. Note that a rough description has already been given in the table above that paragraph, so it doesn't really need to say anything here. How about just "valid only for local repositories"?
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [BOOK] [PATCH] Niggles in Chapter 3
Posted by Chris Pepper <pe...@reppep.com>.
At 1:40 PM +0100 2004/10/02, Julian Foad wrote:
>Please could you read the file "HACKING" in the root directory, at
>least the parts of it that describe submitting a patch. In
>particular, it would be helpful if you could format your log message
>in the required way. Since there are rather few changes in each
>chapter, and they are generally of the same kind in different
>chapters, it would be appropriate to make a single patch containing
>all of them.
Julian,
Sorry, I read doc/book/HACKING, not /HACKING. I was concerned
that some of the language nits were subtle enough to require
explanation; per your suggestion, I've removed those explanations
from the below.
I guessed at the desired level of verbosity for language
cleanup (not mentioning most of the miscellaneous language tweaks).
If more detail is required, please let me know, ideally with a sample
log message illustrating the right level of detail.
Thanks,
Chris Pepper
Suggested log message:
Fix niggles in the book.
Patch submitted by Chris Pepper <pe...@reppep.com>.
Enhancements from Julian Foad <ju...@btopenworld.com>.
* doc/book/book/ch00.xml:
Consistently use "command-line" rather than "commandline".
Capitalise ASCII, as it is an acronym.
* doc/book/book/ch01.xml:
Consistently use "command-line" rather than "commandline".
Remove spaces around '—' to conform with the style guide.
(Note: I didn't actually find this spelled out, but Julian Foad
confirms the preferred style.)
* doc/book/book/ch02.xml:
Remove spaces around '—'.
Remove spaces before </para>.
Clean up some redundant and awkward wording.
* doc/book/book/ch03.xml:
Clean up some redundant and awkward wording.
* doc/book/book/ch05.xml:
Remove spaces around '—'.
* doc/book/book/ch06.xml:
Consistently use "command-line" rather than "commandline".
Remove spaces around '—'.
* doc/book/book/ch09.xml:
Remove spaces around '—'.
Re: [BOOK] [PATCH] Niggles in Chapter 3
Posted by Julian Foad <ju...@btopenworld.com>.
[Niggles in chapters 0,1,2,3]
Thanks for proof-reading the book and submitting these patches. I agree with all of your changes in chapters 0, 1 and 2, and most of these in chapter 3 (exceptions below).
Please could you read the file "HACKING" in the root directory, at least the parts of it that describe submitting a patch. In particular, it would be helpful if you could format your log message in the required way. Since there are rather few changes in each chapter, and they are generally of the same kind in different chapters, it would be appropriate to make a single patch containing all of them.
Here is a partial log message to get you started. It begins with a brief summary of the reason for the patch, and then summarises what was changed in each file.
[[[
Fix niggles in the book.
Patch submitted by Chris Pepper <pe...@reppep.com>.
* doc/book/book/ch00.xml:
Consistently use "command-line" rather than "commandline".
Capitalise ASCII, as it is an acronym. [if you find others, you could just say "Capitalise acronyms."]
Remove spaces around '—' to conform with the style guide.
* doc/book/book/ch01.xml:
[...]
* doc/book/book/ch02.xml:
[...]
* doc/book/book/ch03.xml:
Clean up some redundant and awkward wording. [this single summary is enough to cover several of the changes]
[...]
]]]
Chris Pepper wrote:
> "specify a date by specifying the date" is redundant.
Yes.
> As written, .svn sounds like a read-only area; the injunction is
> really against direct manipulation.
I disagree that the wording makes it sound read-only (it is at worst ambiguous) and that appending "directly" clears up any such confusion. Anyway, indirect manipulation is also wrong except via Subversion itself. Perhaps the sentence is not as clear as it could be, but I don't think this particular change helps.
> "This places your working copy into" is awkward. I believe "This
> places your working copy in" is more correct, but am not certain.
Yes.
> The most important thing about svn add is that it adds, not that
> it's deferred.
Yes.
>> - changes coming from the repository didn't overlap in any
>> - way.</para>
>> + changes coming from the repository didn't overlap.</para>
>
> But of course, Subversion can't guarantee there's no (semantic)
> overlap. Tone it down to what can be guaranteed.
Yes. (Appending "with them" (i.e., with the local changes) would be better still, otherwise the clause can be interpreted as "the changes from the repository didn't overlap with each other".)
> Even better, specify in
> the text that the test used is for changes which affect the same line,
> or whatever svn uses internally.
That would be a possible enhancement to the text if the true test (which also takes into account changes to adjacent and nearby lines) can be described very concisely, but I don't think it is necessary here.
(If you write a formal log message of these changes for us, remember to leave this speculative sentence out of it and just mention the changes that you are making in this patch.)
> Rephrase active use of "log" (which implies adding/editing the log)
> to passive use (for reviewing existing log entries).
Yes.
> The final change is for a complicated sentence with three parts,
> which as written implied all three parts (including the transaction
> itself and discarding the log) take place before the transaction. I have
> tried to disentangle it with minimal revision.
I don't like the version in your patch. It still doesn't separate the clauses enough.
> Alternatively, change:
>
> Before changing anything it writes its intentions to a log file, then
> executes the commands in the log file, and finally removes the log file
> (this is similar in design to a journaled filesystem).
>
> to:
>
> Before changing the repository, Subversion writes its intentions to a
Not the repository, but the working copy.
> log file. Next it executes the commands in the log file to apply the
> requested change. Finally, Subversion removes the log file.
> Architecturally, this is similar to a journaled filesystem).
Apart from that error, this version is good.
Thanks again, and if you are happy to produce a revised, combined patch with a standard-format log message, that would be lovely. Even if you don't we'll still gratefully use your submissions.
- Julian
> Chris Pepper
>
> Index: ch03.xml
> ===================================================================
> --- ch03.xml (revision 11198)
> +++ ch03.xml (working copy)
> @@ -201,7 +201,7 @@
> <title>Revision Dates</title>
> <para>Anywhere that you specify a revision number or revision
> - keyword, you can also specify a date by specifying the date
> + keyword, you can also specify a date
> inside curly braces <quote>{}</quote>. You can even access
> a range of changes in the repository using both dates and
> revisions together!</para>
> @@ -370,7 +370,7 @@
> <filename>.svn</filename>. Usually, directory listing
> commands won't show this subdirectory, but it is nevertheless
> an important directory. Whatever you do, don't delete or
> - change anything in the administrative area! Subversion
> + change anything in the administrative area directly! Subversion
> depends on it to manage your working copy.</para>
>
> </sidebar>
> @@ -378,7 +378,7 @@
> <para>While you can certainly check out a working copy with the
> URL of the repository as the only argument, you can also specify
> a directory after your repository URL. This places your working
> - copy into the new directory that you name. For example:</para>
> + copy in the new directory that you name. For example:</para>
> <screen>
> $ svn checkout http://svn.collab.net/repos/svn/trunk subv
> @@ -636,7 +636,7 @@
> become a child of its parent directory. Note that if
> <filename>foo</filename> is a directory, everything
> underneath <filename>foo</filename> will be scheduled
> - for addition. If you only want to schedule
> + for addition. If you only want to add
> <filename>foo</filename> itself, pass the
> <option>--non-recursive</option> (<option>-N</option>)
> switch.</para>
> @@ -917,7 +917,7 @@
> might have a file in the repository, but you removed
> the file and created a directory in its place, without
> using the <command>svn delete</command> or
> - <command>svn add</command> commands.</para>
> + <command>svn add</command> command.</para>
> </listitem>
> </varlistentry>
>
> @@ -1259,8 +1259,7 @@
> from the repository. The <computeroutput>G</computeroutput>
> stands for mer<computeroutput>G</computeroutput>ed, which
> means that the file had local changes to begin with, but the
> - changes coming from the repository didn't overlap in any
> - way.</para>
> + changes coming from the repository didn't overlap.</para>
> <para>But the <computeroutput>C</computeroutput>
> stands for
> conflict. This means that the changes from the server overlapped
> @@ -1703,7 +1702,7 @@
> <sect2 id="svn-ch-3-sect-5.1">
> <title><command>svn log</command></title>
>
> - <para>To find out information about the history of a file or
> + <para>To find information about the history of a file or
> directory, use the <command>svn log</command>
> command. <command>svn log</command> will provide you with a
> record of who made changes to a file or directory, at what
> @@ -1799,12 +1798,12 @@
> supply no path, Subversion uses the current working
> directory as the default target. As a result, if you're
> operating in a subdirectory of your working copy and attempt
> - to log a revision in which neither that directory nor any of
> - its children was changed, Subversion will give you an empty
> - log. If you want to see what changed in that revision, try
> - pointing <command>svn log</command> directly at the top-most
> - URL of your repository, as in <command>svn log -r 2
> - http://svn.collab.net/repos/svn</command>.</para>
> + to see the log of a revision in which neither that directory
> + nor any of its children was changed, Subversion will show you
> + an empty log. If you want to see what changed in that
> + revision, try pointing <command>svn log</command> directly at
> + the top-most URL of your repository, as in <command>svn log -r
> + 2 http://svn.collab.net/repos/svn</command>.</para>
>
> </sidebar>
> @@ -2047,9 +2046,9 @@
>
> <para>When Subversion modifies your working copy (or any
> information within <filename>.svn</filename>), it tries to do
> - so as safely as possible. Before changing anything, it writes
> - its intentions to a log file, executes the commands in the log
> - file, then removes the log file (this is similar in design to
> + so as safely as possible. Before changing anything it writes
> + its intentions to a log file, then executes the commands in the
> log
> + file, and finally removes the log file (this is similar in
> design to
> a journaled filesystem). If a Subversion operation is
> interrupted (if the process is killed, or if the machine
> crashes, for example), the log files remain on disk. By
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org