You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Greg Stein <gs...@lyra.org> on 2002/07/31 00:26:06 UTC
Best Practices (was: rapidsvn feedback)
All right. This thread is really getting out of hand.
I don't think anybody is *against* writing such a document. Fine. Someone
should just go ahead and write the darned thing. We can then incorporate it,
reference it, or whatever from the standard documentation.
Stop going back and forth about nuances. The simple fact is that the doc
doesn't exist, so all this is premature banter.
On Wed, Jul 31, 2002 at 01:30:10AM +0200, Josef Wolf wrote:
>...
> If you agree with Karl that I am a troll:
He absolutely did not say that. He said something along the lines of "go
trolling for authors on the mailing list". In this case, trolling means to
gather helpers. There is definitely the perjorative form along the lines of
"trolling for flame fests".
The meaning that Karl meant from http://www.dictionary.com/:
v. intr.
1. To fish by trailing a line, as from a moving boat.
2.
1. To wander about; ramble.
2. Slang. To patrol an area in search for someone or something.
3. Music. To sing heartily or gaily.
4. To roll or spin around.
2.1 is the meaning he is going for.
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices (was: rapidsvn feedback)
Posted by Michael Wood <mw...@its.uct.ac.za>.
On Tue, Jul 30, 2002 at 08:57:11PM -0500, Karl Fogel wrote:
> Greg Stein <gs...@lyra.org> writes:
> > The meaning that Karl meant from http://www.dictionary.com/:
> >
> > v. intr.
> >
> > 1. To fish by trailing a line, as from a moving boat.
> > 2.
> > 1. To wander about; ramble.
> > 2. Slang. To patrol an area in search for someone or something.
> > 3. Music. To sing heartily or gaily.
> > 4. To roll or spin around.
> >
> > 2.1 is the meaning he is going for.
> >
> > Cheers,
> > -g
>
> Speaking of nuances!... :-)
And all along I thought it was 2.2 ;)
--
Michael Wood <mw...@its.uct.ac.za>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices (was: rapidsvn feedback)
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Greg Stein <gs...@lyra.org> writes:
> The meaning that Karl meant from http://www.dictionary.com/:
>
> v. intr.
>
> 1. To fish by trailing a line, as from a moving boat.
> 2.
> 1. To wander about; ramble.
> 2. Slang. To patrol an area in search for someone or something.
> 3. Music. To sing heartily or gaily.
> 4. To roll or spin around.
>
> 2.1 is the meaning he is going for.
>
> Cheers,
> -g
Speaking of nuances!... :-)
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Best practices #2
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Scott Lamb <sl...@slamb.org> writes:
> Revised version after Karl's comments.
> Add "Best Practices" chapter to handbook.
>
> * doc/handbook/best_practices.texi:
> New file with tips to use Subversion more effectively.
>
> * doc/handbook/svn-handbook.texi:
> Link to new chapter.
Applied in revision 2916.
You cleaned up some of the overly-verbose phrasing from my email, too,
thanks :-).
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
[PATCH] Best practices #2
Posted by Scott Lamb <sl...@slamb.org>.
Revised version after Karl's comments.
--
Scott Lamb
Add "Best Practices" chapter to handbook.
* doc/handbook/best_practices.texi:
New file with tips to use Subversion more effectively.
* doc/handbook/svn-handbook.texi:
Link to new chapter.
Index: ./doc/handbook/svn-handbook.texi
===================================================================
--- ./doc/handbook/svn-handbook.texi
+++ ./doc/handbook/.svn/tmp/svn-handbook.texi.62476.00001.tmp Thu Aug 8 15:08:56 2002
@@ -97,12 +97,14 @@
* Getting Started:: History, installation and overview of Subversion.
* Client Cookbook:: How to use the Subversion client.
* Repository Administration:: Managing a repository.
+* Best Practices:: Tips to use Subversion more effectively.
* Appendices:: Other useful documents and pointers.
@end menu
@include getting_started.texi
@include client.texi
@include repos_admin.texi
+@include best_practices.texi
@include appendices.texi
@bye
Index: ./doc/handbook/best_practices.texi
===================================================================
--- ./doc/handbook/best_practices.texi
+++ ./doc/handbook/best_practices.texi Thu Aug 8 15:04:54 2002
@@ -0,0 +1,202 @@
+@node Best Practices
+@chapter Best Practices
+
+Tips to use Subversion more effectively.
+
+In this chapter, we'll focus on how to avoid some pitfalls of version
+control systems in general and Subversion specifically.
+
+@menu
+* Source code formatting::
+* When you commit::
+@end menu
+
+
+
+@c ------------------------------------------------------
+@node Source code formatting
+@section Source code formatting
+
+Subversion diffs and merges text files work on a line-by-line basis. They
+don't understand the syntax of programming languages or even know when
+you've just reflowed text to a different line width.
+
+Given this design, it's important to avoid unnecessary reformatting. It
+creates unnecessary conflicts when merging branches, updating working
+copies, and applying patches. It also can drown you in noise when viewing
+differences between revisions.
+
+You can avoid these problems by following clearly-defined formatting rules.
+The Subversion project's own
+@uref{http://svn.collab.net/repos/svn/trunk/HACKING,HACKING} document and
+the @uref{http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html,Code
+Conventions for the Java Programming Language} are good examples.
+
+Tabs are particularly important. Some projects, like Subversion, do not use
+tabs at all in the source tree. Others always use them and define a
+particular tab size.
+
+It can be very helpful to have an editor smart enough to help adhere to
+these rules. For example, @command{vim} can do this on a per-project basis
+with @file{.vimrc} commands like the following:
+
+@verbatim
+autocmd BufRead,BufNewFile */rapidsvn/*.{cpp,h}
+ setlocal ts=4 noexpandtab
+autocmd BufRead,BufNewFile */subversion/*.[ch]
+ setlocal sw=2 expandtab cinoptions=>2sn-s{s^-s:s
+@end verbatim
+
+Check your favorite editor's documentation for more information.
+
+@subsection When you have to reformat
+
+In the real world, we're not always so perfect. Formatting preferences may
+change over time, or we may just make mistakes. There are things you can do
+to minimize the problems of reformatting.
+
+These are good guidelines to follow:
+
+@itemize @bullet
+@item If you're making a sweeping reformatting change, do it in a single
+commit with no semantic changes. Give precise directions on duplicating
+formatting changes.
+@item If you've made semantic changes to some area of code and see
+inconsistent formatting in the immediate context, it's okay to reformat.
+Causing conflicts is not as great a concern because your semantic changes
+are likely to do that anyway.
+@end itemize
+
+Here's an example of a sweeping reformat:
+
+@example
+$ svn co file:///repo/path/trunk indent_wc
+$ indent -gnu indent_wc/src/*.[ch]
+$ svn commit -m 'Ran indent -gnu src/*.[ch]' indent_wc
+@end example
+
+This follows all rules: there were no semantic changes mixed in (no files
+were changed other than through @command{indent}). The @command{indent}
+commandline was given, so the changes can be very easily duplicated. All the
+reformatting was done in a single revision.
+
+Let's say these changes occurred to the trunk at revision 26. The head
+revision is now 42. You created a branch at revision 13 and now want to
+merge it back into the trunk. Ordinarily you'd do this:
+
+@example
+$ svn co file://repo/path/trunk merge_wc
+$ svn merge -r 13:head file://repo/path/branches/mybranch merge_wc
+@dots{} # resolve conflicts
+$ svn commit -m 'Merged branch'
+@end example
+
+But with the reformatting changes, there will be many, many conflicts. If
+you follow these rules, you can merge more easily:
+
+@example
+$ svn co -r 25 file://repo/path/trunk merge_wc
+$ svn merge -r 13:head file://repo/path/branches/mybranch merge_wc
+@dots{} # resolve conflicts
+$ indent -gnu src/*.[ch]
+$ svn up
+@dots{} # resolve conflicts
+$ svn commit -m 'Merged branch'
+@end example
+
+In English, the procedure is:
+
+@itemize @bullet
+@item Check out a pre-reformatting trunk working copy.
+@item Merge all branch changes. Fix conflicts.
+@item Reformat in the same manner.
+@item Update to the head revision. Fix conflicts.
+@item Check in the merged working copy.
+@end itemize
+
+@subsection Ignoring whitespace differences
+
+When viewing differences between revisions, you can customize
+@command{svn diff} output to hide whitespace changes. The @samp{-x} argument
+passes arguments through to GNU diff. Here are some useful arguments:
+
+@table @b
+@item @samp{-b}
+Ignore differences in whitespace only.
+@item @samp{-B}
+Ignore added/removed blank lines.
+@item @samp{-i}
+Ignore changes in case.
+@item @samp{-t}
+Expand tabs to spaces to preserve alignment.
+@item @samp{-T}
+Output a tab rather than a space at the beginning of each line to start on a
+tab stop.
+@end table
+
+The commit emails always show whitespace-only changes.
+@file{commit-email.pl} uses @command{svnlook diff} to get differences, which
+doesn't support the @samp{-x} option.
+
+@subsection Line endings
+
+Different platforms (Unix, Windows, MacOS) have different conventions for
+marking the line endings of text files. Simple editors may rewrite line
+endings, causing problems with diff and merge. This is a subset of the
+formatting problems.
+
+Subversion has built-in support for normalizing line endings. To enable it,
+set the @samp{svn:eol-style} property to ``native''. @xref{Properties}.
+
+
+@c ------------------------------------------------------
+@node When you commit
+@section When you commit
+
+It pays to take some time before you commit to review your changes and
+create an appropriate log message. You are publishing the newly changed
+project anew every time you commit. This is true in two senses:
+
+@itemize @bullet
+@item When you commit, you are potentially destabilizing the head revision.
+Many projects have a policy that the head revision is ``stable'' --- it
+should always parse/compile, it should always pass unit tests, etc. If you
+don't get something right, you may be inconveniencing an arbitrary number of
+people until someone commits a fix.
+@item You can not easily remove revisions. (There is no equivalent to
+@samp{cvs admin -o}.) If you might not want something to be in the
+repository, make sure it is not included in your commit. Check for
+sensitive information, autogenerated files, and unnecessary large files.
+@end itemize
+
+If you later don't like your log message, it is possible to change it. The
+@samp{svnadmin setlog} command will do this locally. You can set up the
+@uref{http://svn.collab.net/repos/svn/trunk/tools/cgi/tweak-log.cgi,tweak-log.cgi}
+script to allow the same thing remotely. All the same, creating a good log
+message beforehand helps clarify your thoughts and avoid committing a mistake.
+
+You should run a @samp{svn diff} before each commit and ask yourself:
+
+@itemize @bullet
+@item do these changes belong together? It's best that each revision is a
+single logical change. It's very easy to forget that you've started another
+change.
+@item do I have a log entry for these changes?
+@end itemize
+
+Defining a log entry policy is also helpful --- the Subversion
+@uref{http://svn.collab.net/repos/svn/trunk/HACKING,HACKING} document is a
+good model. If you always embed filenames, function names, etc. then you can
+easily search through the logs with
+@uref{http://svn.collab.net/repos/svn/trunk/tools/client-side/search-svnlog.pl,search-svnlog.pl}.
+
+You may want to write the log entry as you go. It's common to create a file
+@file{changes} with your log entry in progress. When you commit, use
+@samp{svn ci -F changes}.
+
+@subsection Binary files
+
+Subversion does not have any way to merge or view differences of binary
+files, so it's critical that these have accurate log messages. Since you
+can't review your changes with @samp{svn diff} immediately before
+committing, it's a particularly good idea to write the log entry as you go.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Best Practices
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Scott Lamb <sl...@slamb.org> writes:
> I've had bad luck before with merging not being smart enough to
> realize a change has already been done, especially when I've had to
> adapt it a bit. This would say so explicitly.
I don't see why the --no-merge flag would address that problem, if
running indent before the second update doesn't address it. In any
case, we have a much more general plan for handling repeated merges
(not started implementing yet, but it shouldn't require the user to be
aware of the reindent).
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Best Practices
Posted by Scott Lamb <sl...@slamb.org>.
Karl Fogel wrote:
> Scott Lamb <sl...@slamb.org> writes:
>
>>Then let's say I've checked out revision 62. At revision 65, someone
>>reindented. I've made changes to my working copy and want to commit
>>them without conflict. I could this with:
>>
>> $ svn up -r 64
>> $ svn up -r 65 --no-merge
>> $ indent -gnu src/*.[ch]
>> $ svn up
>
>
> Why not just run indent before you update to rev 65?
I've had bad luck before with merging not being smart enough to realize
a change has already been done, especially when I've had to adapt it a
bit. This would say so explicitly.
--
Scott Lamb
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Best Practices
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Scott Lamb <sl...@slamb.org> writes:
> Then let's say I've checked out revision 62. At revision 65, someone
> reindented. I've made changes to my working copy and want to commit
> them without conflict. I could this with:
>
> $ svn up -r 64
> $ svn up -r 65 --no-merge
> $ indent -gnu src/*.[ch]
> $ svn up
Why not just run indent before you update to rev 65?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Best Practices
Posted by Scott Lamb <sl...@slamb.org>.
Karl Fogel wrote:
> Karl Fogel <kf...@newton.ch.collab.net> writes:
>
>> * If you're working in some area of code anyway, and you see
>> inconsistent indentation in the context lines around that area,
>> it's okay to fix them up too while you're there. Just point out
>> in the log message that there were also formatting changes, so
>> people know to ignore them when scanning the change. In fact,
>> this kind of gradual, as-you-go reindentation is one of the best
>> ways to get a badly indented but active code base into shape,
>> while still avoiding a painful "flag day" on which everything
>> gets reindented at once. (Not that we have that problem, but CVS
>> does, and this is how they're solving it).
>
>
> Oh, I forgot mention an important reason to avoid sweeping
> reformattings. People may have outstanding patches (at home, attached
> to an issue, posted to a website, whatever), and big reformats make
> those patches suddenly inapplicable, or at any rate much harder to
> apply.
Okay, I'll mention that reason.
I have to wonder if there's a fairly easy way to reduce this problem,
similar to how my branch example works.
Hmm, let's say there's an argument to "svn up" or "svn switch" called
"--no-merge". It updates the working copy base files only. Useful for
explicitly saying "I've already merged this".
Then let's say I've checked out revision 62. At revision 65, someone
reindented. I've made changes to my working copy and want to commit them
without conflict. I could this with:
$ svn up -r 64
$ svn up -r 65 --no-merge
$ indent -gnu src/*.[ch]
$ svn up
And there'd be no conflict. Still an inconvenience, but I think less so
if you've made a lot of changes.
--
Scott Lamb
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Best Practices
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Karl Fogel <kf...@newton.ch.collab.net> writes:
> * If you're working in some area of code anyway, and you see
> inconsistent indentation in the context lines around that area,
> it's okay to fix them up too while you're there. Just point out
> in the log message that there were also formatting changes, so
> people know to ignore them when scanning the change. In fact,
> this kind of gradual, as-you-go reindentation is one of the best
> ways to get a badly indented but active code base into shape,
> while still avoiding a painful "flag day" on which everything
> gets reindented at once. (Not that we have that problem, but CVS
> does, and this is how they're solving it).
Oh, I forgot mention an important reason to avoid sweeping
reformattings. People may have outstanding patches (at home, attached
to an issue, posted to a website, whatever), and big reformats make
those patches suddenly inapplicable, or at any rate much harder to
apply.
And the reason that gradual, as-you-go reformatting is good is that it
means you're doing the reformatting in an area of code that's changing
*anyway*, so you're not likely to be making a patch inapplicable
unless it was going to be made inapplicable anyway (by the semantic
changes).
I think it would be good to explain this. People often think of
working copies and the repository, but forget to think about other
places where changes might be stored.
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: removing a revision (Re: [PATCH] Best Practices)
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Michael Price <mp...@atl.lmco.com> writes:
> I tried it over ra_dav. Since only the httpd process was growing with the
> size of the file I figured it was just a ra_dav issue and didn't try the
> local case. The resident set size of the subversion process was only a few
> megabytes and didn't change during the entire operation.
>
> Would you like me to fill out the issue or will you do it?
Would you mind filling it out? You're the "primary source" :-)...
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: removing a revision (Re: [PATCH] Best Practices)
Posted by Michael Price <mp...@atl.lmco.com>.
Karl Fogel writes:
> Okay, thanks. This is broken, of course; memory use should be roughly
> constant, with data arriving streamily. But I think it's a problem we
> sort of knew about, although we don't have an issue filed for it.
>
> Were you doing this over ra_local or ra_dav? Or did you try both?
> Curious to know if it behaved the same...
I tried it over ra_dav. Since only the httpd process was growing with the
size of the file I figured it was just a ra_dav issue and didn't try the
local case. The resident set size of the subversion process was only a few
megabytes and didn't change during the entire operation.
Would you like me to fill out the issue or will you do it?
Michael
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: removing a revision (Re: [PATCH] Best Practices)
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Okay, thanks. This is broken, of course; memory use should be roughly
constant, with data arriving streamily. But I think it's a problem we
sort of knew about, although we don't have an issue filed for it.
Were you doing this over ra_local or ra_dav? Or did you try both?
Curious to know if it behaved the same...
-K
Michael Price <mp...@atl.lmco.com> writes:
> OK. Created a 2GB file containing random data. Created a new
> repository. Checked out the repository. Added the 2GB file. Did the
> commit. If you try this at home... have a lot of disk space because you'll
> need to store:
>
> 1. the original 2GB file
> 2. the 2GB temporary file in .svn/tmp
> 3. the portion of the 2GB file that gets added to the repo
> 4. the log files for the portion that gets added to the repo
>
> On my machine, each process has a hard limit of 448MB data segment size
> and 64MB stack size.
>
> The first time, everything was going along fine until I ran out of disk
> space :)
>
> The second time, after fixing the disk space issue, apache ran until it
> reached its process memory limit and then stopped. It had committed 448MB
> of the file when it stopped.
>
> So, don't commit a file larger than any memory limits on the server or it
> won't work.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: removing a revision (Re: [PATCH] Best Practices)
Posted by Michael Price <mp...@atl.lmco.com>.
Karl Fogel writes:
> > On a side note, I quickly ran 'top' to see how much memory was going to be
> > used while adding this large file. I was pleased to see that subversion's
> > memory use never really increased while the httpd process grew to 65MB and
> > stayed that way. If I add a 2GB file (which I didn't think to try until
> > just now), what's going to happen to httpd? It'll be a few hours until I
> > get to try it so if anyone cares to try first, let me know.
>
> Let us know what happens!
OK. Created a 2GB file containing random data. Created a new
repository. Checked out the repository. Added the 2GB file. Did the
commit. If you try this at home... have a lot of disk space because you'll
need to store:
1. the original 2GB file
2. the 2GB temporary file in .svn/tmp
3. the portion of the 2GB file that gets added to the repo
4. the log files for the portion that gets added to the repo
On my machine, each process has a hard limit of 448MB data segment size
and 64MB stack size.
The first time, everything was going along fine until I ran out of disk
space :)
The second time, after fixing the disk space issue, apache ran until it
reached its process memory limit and then stopped. It had committed 448MB
of the file when it stopped.
So, don't commit a file larger than any memory limits on the server or it
won't work.
Michael
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: removing a revision (Re: [PATCH] Best Practices)
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Michael Price <mp...@atl.lmco.com> writes:
> I was about to ask if there was an easy way to remove revisions short of
> dumping and loading. Last night I had two .pgn files (containing chess
> move lists) in a directory. I wanted to commit the small one (3KB), not
> the large one (73MB). Of course, I end up typing the filename of the large
> one. So am I stuck dumping and loading now to get rid of the enormous
> file?
Yup. Sorry :-(.
> On a side note, I quickly ran 'top' to see how much memory was going to be
> used while adding this large file. I was pleased to see that subversion's
> memory use never really increased while the httpd process grew to 65MB and
> stayed that way. If I add a 2GB file (which I didn't think to try until
> just now), what's going to happen to httpd? It'll be a few hours until I
> get to try it so if anyone cares to try first, let me know.
Let us know what happens!
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
removing a revision (Re: [PATCH] Best Practices)
Posted by Michael Price <mp...@atl.lmco.com>.
Scott Lamb writes:
> I once made the mistake of adding an OpenLDAP configuration file with my
> root DN's password embedded. (Hashed in SSHA, but still.) So tweaking
> later isn't always enough - you might want the incorrect stuff to not be
> in the history at all. Since there's no way to remove a revision (short
> of dumping/loading, and then probably manually re-adding any following
> revisions), best to avoid that.
I was about to ask if there was an easy way to remove revisions short of
dumping and loading. Last night I had two .pgn files (containing chess
move lists) in a directory. I wanted to commit the small one (3KB), not
the large one (73MB). Of course, I end up typing the filename of the large
one. So am I stuck dumping and loading now to get rid of the enormous
file?
On a side note, I quickly ran 'top' to see how much memory was going to be
used while adding this large file. I was pleased to see that subversion's
memory use never really increased while the httpd process grew to 65MB and
stayed that way. If I add a 2GB file (which I didn't think to try until
just now), what's going to happen to httpd? It'll be a few hours until I
get to try it so if anyone cares to try first, let me know.
Michael
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Best Practices
Posted by Scott Lamb <sl...@slamb.org>.
Karl Fogel wrote:
> Scott Lamb <sl...@slamb.org> writes:
>>+@c ------------------------------------------------------
>>+@node When you commit
>>+@section When you commit
>>+
>>+It pays to take some time before you commit to review your changes and
>>+create an appropriate log message. Subversion does not have any convenient
>>+way of removing revisions (there is no equivalent to @samp{cvs admin -o}),
>>+so get it right the first time.
>
>
> The inability to remove committed revisions is unrelated to the
> quality of the log message. If the log message is bad, Subversion
> *does* offer the ability to fix it up afterwards -- so "get it right
> the first time" is not at all necessary here. And while revisions
> can't be removed, more tweaks can always be committed later... So even
> regarding the content of the change, the "get it right the first time"
> advice is a little unconvincing, at least when justified on that
> basis.
I once made the mistake of adding an OpenLDAP configuration file with my
root DN's password embedded. (Hashed in SSHA, but still.) So tweaking
later isn't always enough - you might want the incorrect stuff to not be
in the history at all. Since there's no way to remove a revision (short
of dumping/loading, and then probably manually re-adding any following
revisions), best to avoid that.
I was trying to say the changes can't be modified, not the log message.
I'll clarify. And add your other reason.
--
Scott Lamb
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Best Practices
Posted by Scott Lamb <sl...@slamb.org>.
Karl Fogel wrote:
>>+@subsection Line endings
>>+
>>+Different platforms (Unix, Windows, MacOS) have different conventions for
>>+marking the line endings of text files. Simple editors may rewrite line
>>+endings, causing problems with diff and merge. This is a subset of the
>>+formatting problems.
>>+
>>+Subversion has built-in support for normalizing line endings. To enable it,
>>+set the @samp{svn:eol-style} property to ``native''. @xref{Properties}.
>
>
> "normalizing" doesn't mean much by itself. I think it would be better
> to describe what it actually does, and why it helps solve the problem.
I was trying to avoid duplicating the @samp{svn:eol-style} subsubsection
of the properties node, which already does that. In fact, the cross
reference to it is pretty much the point of this subsection.
Is there a way to do a cross reference to a specific spot within a node?
Otherwise, I might just move much of that to this chapter.
> Okay. Maybe one more iteration, then we can commit this material and
> work on it inline?
Sure. No big objections to the rest of your proposed changes.
--
Scott Lamb
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: [PATCH] Best Practices
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Scott Lamb <sl...@slamb.org> writes:
> Here's the new chapter. I think I did manage to keep it pretty
> Subversion-centered.
Nice work! Several specific comments below, but overall it was very
readable, and I liked the practice of giving examples both as command
transcripts and then as a plain-language outline for clarity -- having
both really helps readers.
> +@c ------------------------------------------------------
> +@node Source code formatting
> +@section Source code formatting
> +
> +Subversion works by creating a set of binary differences between two
> +revisions. It has no knowledge of syntactic vs. sematic differences ---
> +everything is just a difference of bytes.
> +
> +Given this design, it's important to avoid unnecessary syntactic
> +differences. They can cause merges to unnecessarily conflict as well as
> +drowning you in noise when viewing differences between revisions.
I realize that I may have said something misleading about this in an
earlier mail, but:
How exactly does inconsistency between different developers'
indentation styles lead to these problems? I can see how it would
lead to the eventual need for reindentation, which *in turn* leads to
the problems described above, but that's not quite the same thing.
The difference is subtle but important, I think.
It is later reindentation, not the original inconsistent formatting
itself, that leads to the unnecessary noise problem (more on
reindentation later). And so the point of persuading everyone to use
consistent formatting now is to avoid that later reindentation, not
because consistent formatting *itself* causes Subversion to work
better.
The paragraph about syntactic vs semantic is misleading. Subversion's
binary diffing has nothing to do with this problem. In fact, the
`diff' and `merge' commands aren't merely paying attention to bytes,
they're paying attention to lines, because historically a lot of
formats have used line-based syntax. The issue isn't really knowing
syntactic vs semantic differences anyway -- it's about whether the
tool knows anything at all about syntax. And diff/merge *do* know
some very primitive things about syntax, just not much... You see what
I'm getting at here.
> +In the real world, we're not always so perfect. Formatting preferences may
> +change over time, or we may just make mistakes. There are things you can do
> +to minimize the problems of reformatting.
> +
> +Here's a simple rule: never mix formatting and semantic changes in a single
> +revision. Give precise directions on duplicating formatting changes. When
> +possible, combine all formatting changes into a single revision.
A simple rule, but not quite the one that we follow :-).
Many projects use these guidelines instead (CVS does, and I'm pretty
sure that in Subversion we do in practice):
* If you're making a sweeping reformatting/reindentation change,
then yes, do it in an independent commit with no semantic
changes.
* If you're working in some area of code anyway, and you see
inconsistent indentation in the context lines around that area,
it's okay to fix them up too while you're there. Just point out
in the log message that there were also formatting changes, so
people know to ignore them when scanning the change. In fact,
this kind of gradual, as-you-go reindentation is one of the best
ways to get a badly indented but active code base into shape,
while still avoiding a painful "flag day" on which everything
gets reindented at once. (Not that we have that problem, but CVS
does, and this is how they're solving it).
> +@subsection Ignoring whitespace differences
> +
> +When viewing differences between revisions, you may want to not see any
> +whitespace-only changes. @command{svn diff -b} will accomplish this.
> +
> +The commit emails always show whitespace-only changes.
> +@file{commit-email.pl} uses @command{svnlook diff} to get differences, which
> +doesn't support the @samp{-b} option.
"svn diff -x -b", actually. And there may be other flags to diff
worth recommending here, too, check the diff documentation.
> +@subsection Line endings
> +
> +Different platforms (Unix, Windows, MacOS) have different conventions for
> +marking the line endings of text files. Simple editors may rewrite line
> +endings, causing problems with diff and merge. This is a subset of the
> +formatting problems.
> +
> +Subversion has built-in support for normalizing line endings. To enable it,
> +set the @samp{svn:eol-style} property to ``native''. @xref{Properties}.
"normalizing" doesn't mean much by itself. I think it would be better
to describe what it actually does, and why it helps solve the problem.
> +@c ------------------------------------------------------
> +@node When you commit
> +@section When you commit
> +
> +It pays to take some time before you commit to review your changes and
> +create an appropriate log message. Subversion does not have any convenient
> +way of removing revisions (there is no equivalent to @samp{cvs admin -o}),
> +so get it right the first time.
The inability to remove committed revisions is unrelated to the
quality of the log message. If the log message is bad, Subversion
*does* offer the ability to fix it up afterwards -- so "get it right
the first time" is not at all necessary here. And while revisions
can't be removed, more tweaks can always be committed later... So even
regarding the content of the change, the "get it right the first time"
advice is a little unconvincing, at least when justified on that
basis.
See below for another basis on which to justify it.
> +You should run a @samp{svn diff} before each commit and ask yourself:
> +
> +@itemize @bullet
> +@item do these changes belong together? It's best that each revision is a
> +single logical change. It's very easy to forget that you've started another
> +change.
> +@item do I have a log entry for these changes?
> +@end itemize
Nice points. This might be a good place to mention the practice many
projects have of keeping the head of trunk "stable" (buildable,
parseable, whatever the appropriate thing is for that project). That
is, to point out that the repository is not merely a place that stores
your changes -- rather, it effectively *publishes* the newly changed
project anew every time you commit. So if you don't get something
right, you may be inconveniencing an arbitrary number of people until
someone commits a fix. That ought to give one pause :-).
> +Defining a log entry policy is also helpful --- the Subversion
> +@uref{http://svn.collab.net/repos/svn/trunk/HACKING,HACKING} document is a
> +good model. If you always embed filenames, function names, etc. then you can
> +easily search through the logs with
> +@uref{http://svn.collab.net/repos/svn/trunk/tools/client-side/search-svnlog.pl,search-svnlog.pl}.
Yeah. This advice is specific to source code people; in general,
might want to consider what advice would be appropriate for other
kinds of projects too. (I'm not saying it's a bad example, just that
there might be more to say here. The log message policies appropriate
for programming projects may not be a good fit for other types of
projects.)
> +@subsection Binary files
> +
> +Subversion does not have any way to merge or view differences of binary
> +files, so it's critical that these have verbose log messages. Since you
> +can't review your changes with @samp{svn diff} immediately before
> +committing, you might create a new file @file{changes} whenever you start
> +work and modify it as you go. @samp{svn ci -F changes} will use this file as
> +a commit message.
I don't think that the non-diffability of non-text files implies that
the log message must be _verbose_, merely that it should summarize the
change accurately. (Which is really just as true of any other kind of
change...)
And the write-the-log-message-as-you-go thing is used by lots of
people, independently of whether they changed binary files.
Hmmm. I guess I'm just saying that these particular two "best
practices" are not ones I've actually observed in the developers whose
Subversion usage I'm most familiar with (myself, Mike, and Ben). We
all keep running log messages, whether or not binary files are
involved. And we don't aim for verbosity, but for descriptiveness,
again independent of binary files or no binary files. So these
practices may not be as widespread as you assumed... :-)
Okay. Maybe one more iteration, then we can commit this material and
work on it inline?
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
[PATCH] Best Practices
Posted by Scott Lamb <sl...@slamb.org>.
Here's the new chapter. I think I did manage to keep it pretty
Subversion-centered.
I specifically tried to include information from:
* HACKING
<http://svn.collab.net/repos/svn/trunk/HACKING>
* Ben Collins-Sussman: "rapidsvn feedback"
Message-ID: <86...@kepler.ch.collab.net>
<http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=18582>
* Martin Pool: "Re: rapidsvn feedback"
Message-ID: <20...@toey.home>
<http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=19236>
* Karl Fogel: "Re: Best Practices"
Message-ID: <85...@newton.ch.collab.net>
<http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=19087>
--
Scott Lamb
Add "Best Practices" chapter to handbook.
* doc/handbook/best_practices.texi:
New file with tips to use Subversion more effectively.
* doc/handbook/svn-handbook.texi:
Link to new chapter.
Index: ./doc/handbook/svn-handbook.texi
===================================================================
--- ./doc/handbook/svn-handbook.texi
+++ ./doc/handbook/.svn/tmp/svn-handbook.texi.62476.00001.tmp Thu Aug 8 09:05:49 2002
@@ -97,12 +97,14 @@
* Getting Started:: History, installation and overview of Subversion.
* Client Cookbook:: How to use the Subversion client.
* Repository Administration:: Managing a repository.
+* Best Practices:: Tips to use Subversion more effectively.
* Appendices:: Other useful documents and pointers.
@end menu
@include getting_started.texi
@include client.texi
@include repos_admin.texi
+@include best_practices.texi
@include appendices.texi
@bye
Index: ./doc/handbook/best_practices.texi
===================================================================
--- ./doc/handbook/best_practices.texi
+++ ./doc/handbook/best_practices.texi Thu Aug 8 09:05:34 2002
@@ -0,0 +1,159 @@
+@node Best Practices
+@chapter Best Practices
+
+Tips to use Subversion more effectively.
+
+In this chapter, we'll focus on how to avoid some pitfalls of version
+control systems in general and Subversion specifically.
+
+@menu
+* Source code formatting::
+* When you commit::
+@end menu
+
+
+
+@c ------------------------------------------------------
+@node Source code formatting
+@section Source code formatting
+
+Subversion works by creating a set of binary differences between two
+revisions. It has no knowledge of syntactic vs. sematic differences ---
+everything is just a difference of bytes.
+
+Given this design, it's important to avoid unnecessary syntactic
+differences. They can cause merges to unnecessarily conflict as well as
+drowning you in noise when viewing differences between revisions.
+
+You can avoid these problems by following clearly-defined formatting rules.
+The Subversion project's own
+@uref{http://svn.collab.net/repos/svn/trunk/HACKING,HACKING} document and
+the @uref{http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html,Code
+Conventions for the Java Programming Language} are good examples.
+
+Tabs are particularly important. Some projects, like Subversion, do not use
+tabs at all in the source tree. Others always use them and define a
+particular tab size.
+
+It can be very helpful to have an editor smart enough to help adhere to
+these rules. For example, @command{vim} can do this on a per-project basis
+with @file{.vimrc} commands like the following:
+
+@verbatim
+autocmd BufRead,BufNewFile */rapidsvn/*.{cpp,h}
+ setlocal ts=4 noexpandtab
+autocmd BufRead,BufNewFile */subversion/*.[ch]
+ setlocal sw=2 expandtab cinoptions=>2sn-s{s^-s:s
+@end verbatim
+
+Check your favorite editor's documentation for more information.
+
+@subsection When you have to reformat
+
+In the real world, we're not always so perfect. Formatting preferences may
+change over time, or we may just make mistakes. There are things you can do
+to minimize the problems of reformatting.
+
+Here's a simple rule: never mix formatting and semantic changes in a single
+revision. Give precise directions on duplicating formatting changes. When
+possible, combine all formatting changes into a single revision.
+
+Reformatting might go like this:
+
+@example
+$ svn co file:///repo/path/trunk indent_wc
+$ indent -gnu indent_wc/src/*.[ch]
+$ svn commit -m 'Ran indent -gnu src/*.[ch]' indent_wc
+@end example
+
+This follows all rules: there were no semantic changes mixed in (no files
+were changed other than through @command{indent}). The @command{indent}
+commandline was given, so the changes can be very easily duplicated. All the
+reformatting was done in a single revision.
+
+Let's say these changes occurred to the trunk at revision 26. The head
+revision is now 42. You created a branch at revision 13 and now want to
+merge it back into the trunk. Ordinarily you'd do this:
+
+@example
+$ svn co file://repo/path/trunk merge_wc
+$ svn merge -r 13:head file://repo/path/branches/mybranch merge_wc
+@dots{} # resolve conflicts
+$ svn commit -m 'Merged branch'
+@end example
+
+But with the reformatting changes, there will be many, many conflicts. If
+you follow these rules, you can merge more easily:
+
+@example
+$ svn co -r 25 file://repo/path/trunk merge_wc
+$ svn merge -r 13:head file://repo/path/branches/mybranch merge_wc
+@dots{} # resolve conflicts
+$ indent -gnu src/*.[ch]
+$ svn up
+@dots{} # resolve conflicts
+$ svn commit -m 'Merged branch'
+@end example
+
+In English, the procedure is:
+
+@itemize @bullet
+@item Check out a pre-reformatting trunk working copy.
+@item Merge all branch changes. Fix conflicts.
+@item Reformat in the same manner.
+@item Update to the head revision. Fix conflicts.
+@item Check in the merged working copy.
+@end itemize
+
+@subsection Ignoring whitespace differences
+
+When viewing differences between revisions, you may want to not see any
+whitespace-only changes. @command{svn diff -b} will accomplish this.
+
+The commit emails always show whitespace-only changes.
+@file{commit-email.pl} uses @command{svnlook diff} to get differences, which
+doesn't support the @samp{-b} option.
+
+@subsection Line endings
+
+Different platforms (Unix, Windows, MacOS) have different conventions for
+marking the line endings of text files. Simple editors may rewrite line
+endings, causing problems with diff and merge. This is a subset of the
+formatting problems.
+
+Subversion has built-in support for normalizing line endings. To enable it,
+set the @samp{svn:eol-style} property to ``native''. @xref{Properties}.
+
+
+@c ------------------------------------------------------
+@node When you commit
+@section When you commit
+
+It pays to take some time before you commit to review your changes and
+create an appropriate log message. Subversion does not have any convenient
+way of removing revisions (there is no equivalent to @samp{cvs admin -o}),
+so get it right the first time.
+
+You should run a @samp{svn diff} before each commit and ask yourself:
+
+@itemize @bullet
+@item do these changes belong together? It's best that each revision is a
+single logical change. It's very easy to forget that you've started another
+change.
+@item do I have a log entry for these changes?
+@end itemize
+
+Defining a log entry policy is also helpful --- the Subversion
+@uref{http://svn.collab.net/repos/svn/trunk/HACKING,HACKING} document is a
+good model. If you always embed filenames, function names, etc. then you can
+easily search through the logs with
+@uref{http://svn.collab.net/repos/svn/trunk/tools/client-side/search-svnlog.pl,search-svnlog.pl}.
+
+@subsection Binary files
+
+Subversion does not have any way to merge or view differences of binary
+files, so it's critical that these have verbose log messages. Since you
+can't review your changes with @samp{svn diff} immediately before
+committing, you might create a new file @file{changes} whenever you start
+work and modify it as you go. @samp{svn ci -F changes} will use this file as
+a commit message.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Josef Wolf <jw...@raven.inka.de> writes:
> Hmmm, I don't like (1) because it is too smattering. I neither like (2)
> because it describes only a special case (changing whitespace) of the
> (more general) coding-style-issue (see above). While "diff -w" and
> "patch -l" can help you out with changing whitespace to some degree,
> I know of no good solution for changing style from e.g. GNU to K+R or
> vice-versa. Therefore I feel that it is much more important to warn
> of changing style than just changing whitespace.
Good point. After we commit Scott's material (as soon as I climb out
of my coding stack), maybe you/him/both can massage it accordingly.
> I think it might be a good idea to make this document a
> plain-text-file. This way people could just copy+paste the parts
> they think their project would benefit of into their HACKING file.
> Such a decision would imply that it should _not_ go into the
> handbook, since the handbook is not plan-text. It could be even
> splitted into a texinfo-part for the appendix and a plain-text-part
> for copy+paste.
I think you can generate plain text from the handbook.
> An issue with such a document and discussions about it is that it
> could provoke religious wars. I am not sure whether it is always
> possible to avoid such wars. OTOH I think we should definitely keep
> such wars out of the developers list. If we want to continue this
> discussion, it probably should move to the user's mailing-list?
> Isn't it time to activate the user's list now that Alpha is out?
Not yet, I think. We still want feedback to be visible to everyone.
Anyway, religious wars are just as counterproductive on the users list
as they are on the dev list. If the document starts provoking such
wars, we can deal with it then. Thus far, it hasn't. (Earlier
proposals to create a much *broader* document did, but we've
fortunately settled on a Subversion-specific document).
> While we are at the changing-whitespace-topic: IMHO "svn switch" and
> "svn update" should get an option like --ignore-whitespace because
> they often run diff/patch internally to do the merges... Hmmm, maybe
> giving them something like --tabify and --untabify could be a good
> idea, too?
I haven't given it much thought, and frankly can't right now. Maybe
someone else can...
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices
Posted by Josef Wolf <jw...@raven.inka.de>.
On Thu, Aug 01, 2002 at 04:38:01PM -0500, Karl Fogel wrote:
> Josef, can you clear this up by posting a concise description of what
> you envision for this document?
Well, it would be directed to _svn users_, this is why I originally
thought it would be a good idea to put it into an appendix of the
svn handbook. It would try to give hints/guidance/tips for users with
no/little expirience how to create and maintain their own repository
and HACKING file (well, not exactly, but something similar). I think
this is an important thing, because many newbie-errors made in the
early days of the repo are hard to correct once the repo has grown
too savage.
Just to give an example:
You have decided for the svn project that you want to use the GNU
coding style and fixed that in your HACKING file.
The analogous part of this document would look something like this:
"You should pick one coding style in the early days of your
repository. It does not matter which of the many available styles
you choose, but you should be comfortable with it and expect to be
comfortable as long as the repository exists. The important thing
with this is that you start using the choosen style as soon as
possible (best is right from creation of the repo), because changing
style between revisions will put you directly into hell if you ever
need to merge across this specific revision."
Along would go a rationale. Something like I have written in
http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgId=179283
about indent(1).
In an other mail withhin this thread you wrote:
> Hmmm. Let me try to explain myself more clearly: There are two paths
> this specific example could take:
>
> 1. "You should use consistent formatting because it makes your code
> easier to read, and not everyone has wide screens and
> line-ending-tolerant editors."
>
> versus
>
> 2. "If you use only spaces for indentation, and maintain a
> consistent indentation style, then the 'svn diff' command will
> not show spurious diffs. Also, you should know about the
> following options to 'svn diff -x'..."
>
> They're both about formatting, but (2) is geared toward the Subversion
> Handbook, where as (1) is not. I'm always okay with stuff of the (2)
> variety, but feel strongly that we shouldn't include stuff of the (1)
> variety.
Hmmm, I don't like (1) because it is too smattering. I neither like (2)
because it describes only a special case (changing whitespace) of the
(more general) coding-style-issue (see above). While "diff -w" and
"patch -l" can help you out with changing whitespace to some degree,
I know of no good solution for changing style from e.g. GNU to K+R or
vice-versa. Therefore I feel that it is much more important to warn
of changing style than just changing whitespace.
Some further thoughts:
I think it might be a good idea to make this document a
plain-text-file. This way people could just copy+paste the parts
they think their project would benefit of into their HACKING file.
Such a decision would imply that it should _not_ go into the
handbook, since the handbook is not plan-text. It could be even
splitted into a texinfo-part for the appendix and a plain-text-part
for copy+paste.
An issue with such a document and discussions about it is that it
could provoke religious wars. I am not sure whether it is always
possible to avoid such wars. OTOH I think we should definitely keep
such wars out of the developers list. If we want to continue this
discussion, it probably should move to the user's mailing-list?
Isn't it time to activate the user's list now that Alpha is out?
While we are at the changing-whitespace-topic: IMHO "svn switch" and
"svn update" should get an option like --ignore-whitespace because
they often run diff/patch internally to do the merges... Hmmm, maybe
giving them something like --tabify and --untabify could be a good
idea, too?
--
-- Josef Wolf -- jw@raven.inka.de --
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Greg Stein <gs...@lyra.org> writes:
> I certainly can't be positive what Josef is talking about. But I did have an
> idea on why you were getting frustrated trying to make your thoughts clear
> (B&W vs grey), and that I think a simple shut-down on the topic might not be
> entirely Right(tm).
>
> That said: yes, a generic Best Practices for non-SVN topics doesn't belong.
> I did say that. :-) But I just don't want to see us try to control a topic
> that could be beneficial.
Josef, can you clear this up by posting a concise description of what
you envision for this document?
Possibly my understanding of what you want to write is not the same as
yours (and clearly is not the same as Greg's! :-) ).
Thanks,
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices
Posted by Greg Stein <gs...@lyra.org>.
I certainly can't be positive what Josef is talking about. But I did have an
idea on why you were getting frustrated trying to make your thoughts clear
(B&W vs grey), and that I think a simple shut-down on the topic might not be
entirely Right(tm).
That said: yes, a generic Best Practices for non-SVN topics doesn't belong.
I did say that. :-) But I just don't want to see us try to control a topic
that could be beneficial.
Cheers,
-g
On Thu, Aug 01, 2002 at 04:22:20PM -0500, Karl Fogel wrote:
> Greg Stein <gs...@lyra.org> writes:
> > It is black and white in *your* mind. Others do not distinguish it as
> > clearly. Thus, many people see a *very* valid tie-together of SVN and a best
> > practices doc for it.
> >
> > It is fine for /you/ to not want it here, but I think it is a valid topic
> > for this list (I'm not speaking authoritatively here; just a +1 on saying
> > that the topic is fine for this list). CVS has had *years* to build up a set
> > of practices on how to use the thing effectively. SVN is just beginning, and
> > we (the people on this list) are the people that are going to flesh out that
> > information and those best practices.
>
> If Josef is talking about a best practices that is specific to SVN,
> then +1 on talking about it here. (Stuff like "how to arrange
> branches in the repository", etc).
>
> But as far as I can tell, he's talking about a generic Best Practices
> document that has things like "Format your code in 80 columns." Do
> you really think *that* has anything to do with what revision control
> system one is using? And furthermore, he's not talking about the
> HACKING file, which explicitly limits its domain to the Subversion
> project. He's talking about a new document, which claims to be a
> guideline for lots of projects, and which is not Subversion-specific.
>
> I haven't seen anyone else on this list who wants to start the same
> document Josef is talking about.
>
> What you are +1'ing is not the same thing Josef is proposing (or if it
> is, then Josef is not being very clear IMHO).
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
> For additional commands, e-mail: dev-help@subversion.tigris.org
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices
Posted by Scott Lamb <sl...@slamb.org>.
Karl Fogel wrote:
> Keep it about Subversion, or clearly related to Subversion, that's all
> I'm saying.
>
> Is that clearer?
Yeah, and that sounds pretty reasonable to me. Everything I had in mind
was because of the peculiarities of SCM systems and Subversion-specific
information like the diff arguments and svn:eol-style could be included
throughout.
If no one beats me to it (Frisbee-playing and moving and class and work,
oh my), I'll send in a patch along these lines.
--
Scott Lamb
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Scott Lamb <sl...@slamb.org> writes:
> That's not entirely true. I was interested in a chapter or appendix to
> the Subversion Handbook on general best practices for using SCM,
> including stuff like "use a consistent indentation style/correct line
> endings" These are not specific to Subversion but particularly
> important for SCM systems (so diffs aren't obfuscated with
> reindentation, etc). I lost interest when it was clear it wouldn't be
> accepted as part of the handbook. It just wasn't worth it to me to
> create a whole new project for what I expected to be a couple pages of
> tips.
(Sorry to have forgotten about that post of yours!)
Yeah, we should also teach people about the flags to `svn diff' that
make it ignore whitespace. That's fine to include in the Handbook.
Hmmm. Let me try to explain myself more clearly: There are two paths
this specific example could take:
1. "You should use consistent formatting because it makes your code
easier to read, and not everyone has wide screens and
line-ending-tolerant editors."
versus
2. "If you use only spaces for indentation, and maintain a
consistent indentation style, then the 'svn diff' command will
not show spurious diffs. Also, you should know about the
following options to 'svn diff -x'..."
They're both about formatting, but (2) is geared toward the Subversion
Handbook, where as (1) is not. I'm always okay with stuff of the (2)
variety, but feel strongly that we shouldn't include stuff of the (1)
variety.
Keep it about Subversion, or clearly related to Subversion, that's all
I'm saying.
Is that clearer?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices
Posted by Scott Lamb <sl...@slamb.org>.
Karl Fogel wrote:
> I haven't seen anyone else on this list who wants to start the same
> document Josef is talking about.
That's not entirely true. I was interested in a chapter or appendix to
the Subversion Handbook on general best practices for using SCM,
including stuff like "use a consistent indentation style/correct line
endings" These are not specific to Subversion but particularly important
for SCM systems (so diffs aren't obfuscated with reindentation, etc). I
lost interest when it was clear it wouldn't be accepted as part of the
handbook. It just wasn't worth it to me to create a whole new project
for what I expected to be a couple pages of tips.
--
Scott Lamb
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Greg Stein <gs...@lyra.org> writes:
> It is black and white in *your* mind. Others do not distinguish it as
> clearly. Thus, many people see a *very* valid tie-together of SVN and a best
> practices doc for it.
>
> It is fine for /you/ to not want it here, but I think it is a valid topic
> for this list (I'm not speaking authoritatively here; just a +1 on saying
> that the topic is fine for this list). CVS has had *years* to build up a set
> of practices on how to use the thing effectively. SVN is just beginning, and
> we (the people on this list) are the people that are going to flesh out that
> information and those best practices.
If Josef is talking about a best practices that is specific to SVN,
then +1 on talking about it here. (Stuff like "how to arrange
branches in the repository", etc).
But as far as I can tell, he's talking about a generic Best Practices
document that has things like "Format your code in 80 columns." Do
you really think *that* has anything to do with what revision control
system one is using? And furthermore, he's not talking about the
HACKING file, which explicitly limits its domain to the Subversion
project. He's talking about a new document, which claims to be a
guideline for lots of projects, and which is not Subversion-specific.
I haven't seen anyone else on this list who wants to start the same
document Josef is talking about.
What you are +1'ing is not the same thing Josef is proposing (or if it
is, then Josef is not being very clear IMHO).
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices
Posted by William Uther <wi...@cs.cmu.edu>.
On 1/8/02 5:31 PM, "Greg Stein" <gs...@lyra.org> wrote:
> On Thu, Aug 01, 2002 at 02:10:29PM -0500, Karl Fogel wrote:
>> ...
>> Sigh. I'm genuinely frustrated at my inability to make this clear:
>
> It is black and white in *your* mind. Others do not distinguish it as
> clearly. Thus, many people see a *very* valid tie-together of SVN and a best
> practices doc for it.
>
> It is fine for /you/ to not want it here, but I think it is a valid topic
> for this list (I'm not speaking authoritatively here; just a +1 on saying
> that the topic is fine for this list). CVS has had *years* to build up a set
> of practices on how to use the thing effectively. SVN is just beginning, and
> we (the people on this list) are the people that are going to flesh out that
> information and those best practices.
Maybe this would be good on the users list?
It isn't particularly related to svn development, but it is somewhat related
to svn use.
\x/ill :-}
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices
Posted by Greg Stein <gs...@lyra.org>.
On Thu, Aug 01, 2002 at 02:10:29PM -0500, Karl Fogel wrote:
>...
> Sigh. I'm genuinely frustrated at my inability to make this clear:
It is black and white in *your* mind. Others do not distinguish it as
clearly. Thus, many people see a *very* valid tie-together of SVN and a best
practices doc for it.
It is fine for /you/ to not want it here, but I think it is a valid topic
for this list (I'm not speaking authoritatively here; just a +1 on saying
that the topic is fine for this list). CVS has had *years* to build up a set
of practices on how to use the thing effectively. SVN is just beginning, and
we (the people on this list) are the people that are going to flesh out that
information and those best practices.
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices (was: rapidsvn feedback)
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Josef Wolf <jw...@raven.inka.de> writes:
> > No, *not* in the svn repo. In its own repo. New document, new
> > project. Not related to Subversion.
>
> Ummm. Do we really want to run an own repo for just a couple of pages?
^^^^
I see I'm not getting through, here :-).
This is not "we". This document is *your* project (plus anyone else
who wants to join you). It is not part of the Subversion project, and
should not be discussed nor developed here.
Josef, I'm sorry to keep posting saying the same thing. But what I
want to avoid is this list getting swamped with mails about generic
Best Practices (a topic which is sure to generate huge, noisy
threads).
> But maybe you are right and it would actually get a lot of pages, so
> it would make sense to separate it. So give me some days to put the
> pieces together and _then_ determine whether/where we want to put the
> result.
Put it anywhere you want, as long as it's not the Subversion
repository.
Sigh. I'm genuinely frustrated at my inability to make this clear:
Imagine you were starting a new project, to write a GUI for
controlling satellites in orbit. You're looking for a place to put
that project. Now, *why* would you post on the Subversion dev list to
discuss the project and where to put it?
You wouldn't, because it's a different project, of course.
THAT's the situation you're in with this document.
So ***please*** stop posting about it here, okay?
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices (was: rapidsvn feedback)
Posted by Josef Wolf <jw...@raven.inka.de>.
On Thu, Aug 01, 2002 at 10:41:47AM -0500, Karl Fogel wrote:
> > I still think it is not worth to create a separate document because
[ ... ]
> No, *not* in the svn repo. In its own repo. New document, new
> project. Not related to Subversion.
Ummm. Do we really want to run an own repo for just a couple of pages?
> Of course, most of this stuff is *already* in the svn repo, in the
> HACKING file.
The HACKING file describes the politics of the _svn_ project. This is
different from a file with suggestions to newbies how to run _their_
projects.
But maybe you are right and it would actually get a lot of pages, so
it would make sense to separate it. So give me some days to put the
pieces together and _then_ determine whether/where we want to put the
result.
--
-- Josef Wolf -- jw@raven.inka.de --
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices (was: rapidsvn feedback)
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Josef Wolf <jw...@raven.inka.de> writes:
> I still think it is not worth to create a separate document because
> most of the things I can think of to put there are already written by
> Ben Collins-Sussman in his original article which was the start of
> this thread. There are only two or three Items I would like to
> add. But when the majority of the core team thinks it should be a
> separate document, I will try to put the peaces together so someone
> could commit it into the svn repo. After a while (1.0?) we can again
> take a look at it and let it alone if it has grown large or move it
> into the appendix of the handbook if they are still only a couple of
> pages.
Sorry to have to restate this again:
No, *not* in the svn repo. In its own repo. New document, new
project. Not related to Subversion.
Of course, most of this stuff is *already* in the svn repo, in the
HACKING file. That's the document you want. It exists. We've had it
for a long time. It is the guide to Subversion contributors, and a
handbook section on contributing to Subversion can of course reference
it. But it's there because it's what a Subversion contributor has to
know. It's Subversion-specific -- it is not a separate project to
document the best practices of all open source projects.
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Best Practices (was: rapidsvn feedback)
Posted by Josef Wolf <jw...@raven.inka.de>.
On Tue, Jul 30, 2002 at 05:26:06PM -0700, Greg Stein wrote:
> I don't think anybody is *against* writing such a document. Fine. Someone
> should just go ahead and write the darned thing. We can then incorporate it,
> reference it, or whatever from the standard documentation.
I still think it is not worth to create a separate document because
most of the things I can think of to put there are already written by
Ben Collins-Sussman in his original article which was the start of
this thread. There are only two or three Items I would like to
add. But when the majority of the core team thinks it should be a
separate document, I will try to put the peaces together so someone
could commit it into the svn repo. After a while (1.0?) we can again
take a look at it and let it alone if it has grown large or move it
into the appendix of the handbook if they are still only a couple of
pages.
I would start out with a plain text document, because I have (yet) no
clue how to write texinfo. It would be nice if someone could point me
to a texinfo-HOWTO, so I could rewrite it.
Opinions?
> > If you agree with Karl that I am a troll:
> He absolutely did not say that.
Oh! Thanks for clearing this up. As you can easily see, english is
not my native language. I have heard the word "troll" only on Usenet
before, and was misguided by the different meaning. Karl, I'm sorry
that I misunderstood you this way.
--
-- Josef Wolf -- jw@raven.inka.de --
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org