You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
179 lines
9.1 KiB
179 lines
9.1 KiB
<?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>
|