Initial import
git-svn-id: http://moon:8086/svn/software/trunk/libsrc/xerces-c-3.0.0@1 b431acfa-c32f-4a4a-93f1-934dc6c82436
This commit is contained in:
Executable
+179
@@ -0,0 +1,179 @@
|
||||
<?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>
|
||||
Reference in New Issue
Block a user