You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by da...@cocoon.zones.apache.org on 2006/08/01 17:20:00 UTC
[DAISY] Created: Tips for committers

A new document has been created.

http://cocoon.zones.apache.org/daisy/documentation/1196.html

Document ID: 1196
Branch: main
Language: default
Name: Tips for committers
Document Type: Cocoon Document
Created: 8/1/06 3:19:45 PM
Creator (owner): Helma van der Linden
State: publish

Parts
=====

Content
-------
Mime type: text/xml
Size: 3687 bytes
Content:
<html>
<body>

<h1>Overview</h1>

<p>These are some tips to help committers to keep our Subversion (SVN)
repository clean. See also
<a href="http://www.apache.org/dev/committers.html">Committers FAQ</a> and
<a href="http://www.apache.org/dev/pmc.html">PMC FAQ</a>.</p>

<h1>Coding Style Guidelines</h1>

<p>We do not want to get too concerned about style, other than a few obvious
things such as whitespace. Basically just follow the style that is already used
by the files that you are working on. We loosely follow the
<a href="http://java.sun.com/docs/codeconv/">Sun Java Style Guide</a>.</p>

<h1>Consistent whitespace</h1>

<p>Whitespace can cause big problems with SVN. If it is inconsistent, then diffs
are very hard to follow - actual changes become lost in the noise of whitespace
changes. Some developers use editors that attempt to automatically format the
whitespace. The trouble is that if SVN files are inconsistent, some of those
editors just make it worse.</p>

<p>The solution comes in two parts:</p>

<p>When a committer adds a new file, they need to ensure that the file has the
correct line endings for their own operating system, and that either their SVN
client automatically sets the EOL settings for the file based upon the file
extension, or they must do:</p>

<pre>svn add myfile.txt
svn propset svn:eol-style native myfile.txt
</pre>

<p>is that some committers who have a proper editor should occasionally correct
the whitespace across all SVN files, applying the following rules.</p>

<p>For all text files:</p>

<ul>
<li>Replace all tabs with spaces.</li>
<li>No trailing whitespace.</li>
<li>No MS-DOS line endings.</li>
<li>Newline at end-of-file.</li>
<li>Single whitespace between words.</li>
</ul>

<p>For all Java source files, as for text files plus:</p>

<ul>
<li>Use 4-space indentation.</li>
</ul>

<p>For all XML source files, as for text files plus:</p>

<ul>
<li>Use 2-space indentation.</li>
<li>No whitespace at start-of-file.</li>
<li>No whitespace at end-of-file (except of course a newline).</li>
</ul>

<h1>dos2unix and other control-characters</h1>

<p>If you are on a UNIX system, when you receive a patch from a contributor on
Windows then do a 'dos2unix'. If you are on a Windows system, then ensure that
you have a proper SVN client (it is supposed to convert to UNIX line-endings
when you commit).</p>

<p>Here is one UNIX way to find all plain-text files that have DOS line-endings
(and maybe mixed line-endings). There seem to be many images and jar archives
that contain carriage-returns, so to list only the plain-text files:</p>

<pre>find . -type f | xargs grep -l '^M' | xargs file | \
grep -i -w text | cut -f1 -d:

To add the ^M use "Ctrl-v Ctrl-m" at the command-line.
Note that copy-and-paste will not work.
The -w can be omitted, but might then match some extra filenames.
</pre>

<p>To instead find <em>all</em> files (including images and foreign jar
archives) that have DOS line-endings: <tt>find . -type f | xargs grep -l
'^M'</tt></p>

<p>Here is one way to find files that have <em>any</em> hidden control
characters: <tt>find . -type f | xargs grep -l '[[:cntrl:]]'</tt></p>

<h1>Valid XML instances</h1>

<p>Many of us have wasted time with a broken build due to xml validation errors.
Would all committers please either use a proper xml editor or validate their
xdocs with one of the following commands:</p>

<pre>onsgmls -c $COCOON_HOME/src/webapp/WEB-INF/entities/catalog \
-wall -wxml -s mydoc.xml
      </pre>

<pre>export SGML_CATALOG_FILES=$COCOON_HOME/src/webapp/WEB-INF/entities/catalog
xmllint --valid --catalogs --noout mydoc.xml
      </pre>

<pre>forrest validate-xdocs
      </pre>

</body>
</html>

Collections
===========
The document belongs to the following collections: generaldocs