| <?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&) |
| { |
| 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> |