<?xml version="1.0" encoding = "iso-8859-1" standalone="no"?>
<!--
 * Copyright 2004 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
-->

<!DOCTYPE faqs SYSTEM "sbk:/style/dtd/faqs.dtd">

<faqs title='FAQs for Contributors'>
    <faq title="Submitting Patches">
    <q>I have a problem and I think I know how to fix it.  How can I
        communicate my ideas to the Xerces team?
    </q>
    <a>
        <p>To maximize the probability that your ideas will grab the
        attention of one of the Xerces developers who knows about the
        area of the parser you're concerned with, you should follow
        these steps:
    </p>
    <ol>
        <li>Check out and build the most recent Xerces code.  For
            instructions on how to do this, see <jump
            href="http://xml.apache.org/cvs.html">Apache XML Project CVS
            Information</jump>.  If you do this, you can confirm that your
            bug still exists and has not been fixed since the last
            release.
        </li>
        <li>
            Write up your bug report as per the instructions described in
            the <jump href="bug-report.html">Bug-Reporting</jump> page.            
        </li>
        <li>
            Describe why your solution works.
        </li>
        <li>
            Prepare a patch to fix Xerces code.  To do this, when you
            have applied your changes to a local copy of the most
            recent xerces source code, do <code>cvs diff -u
            file</code> for each file you&apos;ve changed.
            Keep in mind the coding guidelines for &XercesCName; as
            described below.
        </li>
        <li>
            Zip (or tar) up your patches.  If you send them in the
            body of a message or bug report they are very difficult to
            apply.
        </li>
        <li>
            Submit a bug report on <jump href="http://nagoya.apache.org/jira">Jira</jump>,
	     	the Apache bug database.  Pick the product "Xerces-C++"
            (remembering to attach your patches and test code)
            or, if you think your patch might need some discussion,
            post it to the xerces-c-dev list.
        </li>
    </ol>
    </a>
    </faq>

    <faq title="Release Policy">
    <q>What are the release policies for &XercesCName;?
    </q>
    <a>
      <p>The informal release policies for &XercesCName; are (using a versioning of version.release.modification):</p>
      <ul>
      <li>We don't try to enforce binary compatibility between new versions and releases.</li>
      <li>New versions and releases will be delivered when a certain number of bug fixes/new features have been added 
      (as decided by the committers) or when a dependent product, such as XALAN, wants to ship a new release that uses new Xerces features.</li>      
      <li>New modification levels will almost never be issued, the only exception is a showstopper bug encountered within
      a release. if no commit has been made on the trunk which would result in binary incompatibility, and no commit has been made that is not thought to
      be release-quality, then the modification release can be created by tagging the trunk; otherwise, a branch (new release) will need to be created and the show stopper
      fixed there.</li>
      <li>Any normal bug is fixed only in the HEAD branch (latest development code).</li>
      </ul>
            
      <p>The specific source and binary compatibility objectives for these release policies and the corresponding allowed source changes are:</p>
      <ul>
      <li>x.x.x to x.x.y: the API is the same to ensure binary compatibility.</li>
      <ul>
      <li>To maintain binary compatibility the allowed source code changes are:</li>
      <ul>
      <li>Add new non-virtual functions.</li>
      <li>Add new classes.</li>
      <li>Add new STATIC data members.</li>           
      </ul>      
      <li>To maintain binary compatibility you cannot:</li>
      <ul>
      <li>Add new virtual functions as this will change the layout of the virtual function table.</li>
      <li>Change the order of virtual functions in the class declaration.</li>
      <li>Change the signature of a function (including adding additional parameters with defaults).</li>
      <li>Change the access specifier (private/public/protected) on functions or data members as this may be part of the signature with some compilers.</li>
      <li>Add new data members to a class (other than STATIC members).</li>
      <li>Change the order of data members in the class declaration (other than STATIC members).</li>
      <li>Change the class hierarchy (other than adding new classes).</li>
      </ul>
      <li>Methods that are deprecated should be marked with the JavaDoc tag @deprecated in the header file.</li>
      </ul>
      <li>x.x.x to x.y.z: the API is source code compatible but not binary compatible (a recompilation of an application that uses the public headers of &XercesCName; should work).</li>
      <ul>
      <li>This means that to maintain release to release source code compatibility the signature of public methods can only be 
      changed by adding default parameters.</li>
      <li>Signatures of private and protected methods can be changed and/or removed.</li>
      <li>Methods that are deprecated should be marked with the JavaDoc tag @deprecated in the header file.</li>
      </ul>      
      <li>x.x.x to a.b.c: the API may not be source code compatible and is not binary compatible (a recompilation of an application using &XercesCName; may fail).</li>
      <ul>
      <li>In this situation, a separate branch of the code will be created so that bug fixes may be applied to the last version.</li>
      <li>Deprecated methods may be removed.  Deprecated methods that are removed should be documented in the migration information (migration.xml).</li>
      </ul>
      </ul>
    </a>
    </faq>
    
    <faq title="Coding Conventions">
    <q>What are the coding conventions for &XercesCName;?
    </q>
    <a>    
      <p>As with any coding effort, there are always arguments over what coding conventions to use.  Everyone thinks
      that they have the best style which leads to the entire source tree looking different.  This causes consternation
      as well as eye fatigue on subsequent developers that need to maintain the code.  Therefore, we are going to 
      make an attempt at defining some basic coding conventions for &XercesCName;.  When committing files or providing 
      patches please keep them in mind:</p>
      <ol>      
      <li>All classes should have a constructor, destructor, assignment operator and copy constructor to 
      avoid compiler generated default versions of these.</li>
      <ul>
      <li>If a class contains only static methods, only a private constructor is required.</li>
      <li>If a class contains any virtual methods, the destructor should be virtual.</li>
      <li>If a class has a public or protected constructor, it should declare private assignment operator
      and copy constructor which are not implemented (unless of course you need either of these).</li>
      </ul> 
      
      <li>If you add a catch(...) block be sure to add the following block
      <code> 
      catch(const OutOfMemoryException&amp;)
	{
		throw;
	}
      </code> so the OutOfMemory condition does not get absorbed.</li>
		
      <li>If you change the serialization format (by adding something to be serialized or removing something that 
      was serialized) increment the XERCES_GRAMMAR_SERIALIZATION_LEVEL constant in XercesVersion.hpp.</li>
      
      <li>If a class allocates memory or is instantiated with new then it should inherit from XMemory.</li>
      
      <li>Use a tab size of 4 and insert them as spaces instead of keeping tabs.</li>
      
      <li>The code is written to be platform independent.  Platform specific code should only be in the 
      util/Platforms, util/Transcoders, util/MsgLoaders, and util/NetAccessors directories.</li>
      
      <li>The header file name and the source file name should both be named corresponding to the primary 
      class they contain.  For example class StringPool should be in the header file StringPool.hpp and in 
      the source file StringPool.cpp.</li>
      
      <li>In general, code should be documented with comments.  Use JavaDoc tags to describe methods.</li>
      
      <li>The naming convention for ENUMS should be choosen to be unique and descriptive
      (i.e. INVALID or UNKNOWN) to avoid colliding with predefined macros in other
      products.  The current style of using ALL CAP enums should be phased out with
      Mixed Case instead, except for names specified in standards (for example, TEXT_NODE
      should not be converted to mixed case for standards compliance).</li>           
      
      </ol>           
    </a>
    </faq>
    
</faqs>    
