doc/faq-contributing.xml

<?xml version="1.0" encoding = "iso-8859-1" standalone="no"?>
<!--
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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='Contributing to &XercesCName;'>
    <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 &XercesCName; team?
    </q>
    <a>
        <p>To maximize the probability that your ideas will grab the
        attention of one of the &XercesCName; 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 &XercesCName; code.  For
            instructions on how to do this, see <jump href="&RepURI;">&XercesCName;
            Repository 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="&BugURI;">Bug-Reporting</jump> page.
        </li>
        <li>
            Describe why your solution works.
        </li>
        <li>
            Prepare a patch to fix &XercesCName; code.  To do this, when you
            have applied your changes to a local copy of the most
            recent &XercesCName; source code, do <code>svn diff file</code>
	    for each file you have 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 to the &XercesCName; bug database as
            described on the <jump href="&BugURI;">Bug-Reporting</jump> page.
            Pick the product "&XercesCName;" (remembering to attach your patches
            and test code) or, if you think your patch might need some discussion,
            post it to the <jump href="&MailURI;">developer mailing list</jump>.
        </li>
        <li>
            If you are submitting a substantial amount of code, provide the
            information required in the Contributors section of the Project
            Charter.
        </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).</li>
      <li>New modification levels will almost never be issued, the only exception is a showstopper bug encountered within
      a release.</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 Doxygen 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 Doxygen 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/FileManagers, util/MutexManagers, 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 Doxygen tags to describe methods.</li>

      <li>The naming convention for enumerations should be chosen 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>