[PATCH] Best Practices
From: Scott Lamb <slamb_at_slamb.org>
Date: 2002-08-08 17:01:30 CEST
Here's the new chapter. I think I did manage to keep it pretty
I specifically tried to include information from:
* HACKING
--
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
Received on Thu Aug 8 17:01:51 2002
|
This is an archived mail posted to the Subversion Dev mailing list.
This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.