Re: Best Practices

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