logging-log4j-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From c...@apache.org
Subject cvs commit: logging-log4j/src/xdocs faq.xml
Date Fri, 03 Sep 2004 13:14:19 GMT
ceki        2004/09/03 06:14:19

  Modified:    src/xdocs faq.xml
  Log:
  -Added a question about contributing to the FAQ.
  -Minor changes or enhancemetns to other questions
  
  Revision  Changes    Path
  1.2       +55 -14    logging-log4j/src/xdocs/faq.xml
  
  Index: faq.xml
  ===================================================================
  RCS file: /home/cvs/logging-log4j/src/xdocs/faq.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- faq.xml	13 Aug 2004 18:22:51 -0000	1.1
  +++ faq.xml	3 Sep 2004 13:14:19 -0000	1.2
  @@ -746,7 +746,7 @@
   	<ol>
   
   	  <li>
  -	    <b>Write a test case for your contribution.</b>
  +	    <p>Write a test case for your contribution.</p>
   
   	    <p>There is nothing more irritating than finding the bugs
   	    in debugging (i.e. logging) code. Writing a test case
  @@ -762,23 +762,36 @@
   	    <p>Stick to the existing indentation style even if you hate it.</p>
   	    
   	    <p>Alternating between indentation styles makes it hard to
  -	    understand the source code. Make it hard on yourself but
  -	    easier on others. Log4j follows the <a
  +	    understand the source code. Make it a little harder on
  +	    yourself but easier on others.
  +	    </p>
  +
  +	    <p>Log4j has adopted a rather conservative approach by
  +	    following the <a
   	    href="http://java.sun.com/docs/codeconv/">Code Conventions
  -	    for the JavaTM Programming Language</a>.
  +	    for the JavaTM Programming Language</a>. <b>We use 2 (two)
  +	    spaces for indentation and no tabs.</b>
   	    </p>
   	  </li>
   
   	  <li>
  -	    <p><b>Do not both modify the code and change the
  -	    indentation in a single commit.</b>.</p>
  +	    <p>Please do not both modify the code and change the
  +	    indentation in a single commit.</p>
   	    
   	    <p>If you change the code and reformat it at the same time
  -	    and then commit, the commit notification message will not
  -	    be easy to read. It will contain many diff associated with
  -	    the change in indentation plus actual changes to the code
  -	    logic.
  +	    and then commit, the commit notification message will be
  +	    hard to read. It will contain many diffs associated with
  +	    the reformatting in addition to logical changes.
  +	    </p>
  +
  +	    <p>If you must reformat and change the code, then perform
  +	    each step separately. For example, reformat the code and
  +	    commit. Following that, you can change the logic and
  +	    commit. The two steps can be performed in the reverse
  +	    order just as well. You can first change the logic and
  +	    commit and only later reformat and commit.
   	    </p>
  +
   	  </li>
   	  <li>
   	    <p>Make every effort to stick to the JDK 1.1 API.</p>
  @@ -796,8 +809,8 @@
   	  </li>
   	  
   	  <li>
  -	    <p>Identify yourself as the contributor at the top of the
  -	    relevant file. 
  +	    <p>Identify yourself as a contributor at the top of the
  +	    relevant file.
   	    </p>
   	  </li>
   	  <li>
  @@ -808,15 +821,43 @@
   	    </p>
   	  </li>
   	  <li>
  -	    <p>Did I mention sticking with the indentation style? </p>
  +	    <p>Did we mention sticking with the indentation style? </p>
   	  </li>
  -	  <li><p>Did I mention writing test cases? </p>
  +	  <li><p>Did we mention writing test cases? </p>
   	  </li>
   	  
   	</ol>
         </answer>
       </question>
   
  +    <question>
  +      <title>How can I contribute a new question/answer to this
  +      document?</title>
  +      <answer>
  +	<p>Log4j uses <a
  +	href="http://jakarta.apache.org/velocity/anakia.html">velocity-anakia</a>
  +	to generate its web-site, including this FAQ. We have devised
  +	special macros to help us automatically generate labeled
  +	question/answer pairs.
  +	</p>
  +
  +	<p>If you are not a commiter, you can simply submit your new
  +	question/answer pair to the log4j-dev@logging.apache.org
  +	mailing list. The committers will take it from there.
  +	</p>
  +
  +	<p>If you are a committer, then you must edit the
  +	<em>/src/xdocs/faq.xml</em> file. The format of the file
  +	should be self-evident. After you have made your changes, run
  +	the command
  +	</p>
  +	<pre class="source">ant site</pre>
  +
  +	<p>After the appropriate transformation, your changes should
  +	appear in the file <em>/docs/faq.html</em>.
  +	</p>
  +      </answer>
  +    </question>
     </faqSection>
   </body>
   </document>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org


Mime
View raw message