cargilld 2004/09/21 14:54:12 Added: c/doc faq-contributing.xml Log: Create new faq on contributing: contains release policy and coding conventions. Revision Changes Path 1.1 xml-xerces/c/doc/faq-contributing.xml Index: faq-contributing.xml =================================================================== <?xml version="1.0" encoding = "iso-8859-1" standalone="no"?> <!-- * Copyright 1999-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've changed. Keep in mind the coding quidelines 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&) { 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> </ol> </a> </faq> </faqs>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
