[VOTE]: Xerces-C Release Policy & Coding Conventions

[David Cargill]

Hi Xerces-C Committers,
I would like to have a vote on adopting the release policy and coding
conventions attached in the forwarded note below.

+1

Regards,
David A. Cargill
XML Parser Development
IBM Toronto Lab
(905) 413-2371, tie 969
[EMAIL PROTECTED]
----- Forwarded by David Cargill/Toronto/IBM on 09/15/2004 01:52 PM -----
                                                                           
             David                                                         
             Cargill/Toronto/I                                             
             BM                                                         To 
                                       [EMAIL PROTECTED]         
             09/02/2004 04:21                                           cc 
             PM                                                            
                                                                   Subject 
                                       Fw: Xerces-C Release Policy &       
                                       Coding Conventions                  
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           




Hi,
Earlier this year (Feb 9th to be precise) Alberto posted the "informal"
release policy for Xerces-C (
http://marc.theaimsgroup.com/?l=xerces-c-dev&m=107632550720436&w=2).  I
have taken this information and created a new faq-contributing.xml file to
be included in the doc directory.  I also included a section on Coding
Conventions in this file to describe what I think are the main coding
conventions being used in Xerces-C.

Here is the html version of the file (after running createDocs.bat):
                                                                    
 (See attached file: faq-contributing.html)                         
                                                                    
                                                                    

I welcome feedback on the release policies and coding conventions.

Committers: I am hoping to be able to include this file in the Xerces-C 2.6
GA later this month.  So in a few weeks I will request a vote on adopting
the release policies and coding conventions.  Thanks.

Regards,
David A. Cargill
XML Parser Development
IBM Toronto Lab
(905) 413-2371, tie 969
[EMAIL PROTECTED]

Title: FAQs for Contributors

Questions   Submitting Patches Release Policy Coding Conventions I have a problem and I think I know how to fix it. How can I communicate my ideas to the Xerces team?   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: Check out and build the most recent Xerces code. For instructions on how to do this, see Apache XML Project CVS Information. If you do this, you can confirm that your bug still exists and has not been fixed since the last release. Write up your bug report as per the instructions described in the Bug-Reporting page. Describe why your solution works. 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 cvs diff -u file for each file you've changed. Keep in mind the coding quidelines for Xerces-C++ as described below. 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. Submit a bug report on Jira, 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. What are the release policies for Xerces-C++?   The informal release policies for Xerces-C++ are (using a versioning of version.release.modification): We don't try to enforce binary compatibility between new versions and releases. 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. 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. Any normal bug is fixed only in the HEAD branch (latest development code). The specific source and binary compatibility objectives for these release policies and the corresponding allowed source changes are: x.x.x to x.x.y: the API is the same to ensure binary compatibility. To maintain binary compatibility the allowed source code changes are: Add new non-virtual functions. Add new classes. Add new STATIC data members. To maintain binary compatibility you cannot: Add new virtual functions as this will change the layout of the virtual function table. Change the order of virtual functions in the class declaration. Change the signature of a function (including adding additional parameters with defaults). Change the access specifier (private/public/protected) on functions or data members as this may be part of the signature with some compilers. Add new data members to a class (other than STATIC members). Change the order of data members in the class declaration (other than STATIC members). Change the class hierarchy (other than adding new classes). Mark deprecated methods as deprecated using the JavaDoc tag @deprecated. x.x.x to x.y.z: the API is source code compatible but not binary compatible (a recompilation of an application using Xerces-C++ should work). This means that to maintain release to release source code compatibility the signature of public methods can only be changed by adding default parameters. Signatures of private and protected methods can be changed and/or removed. Mark deprecated methods as deprecated using the JavaDoc tag @deprecated. 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 Xerces-C++ may fail). In this situation, a separate branch of the code will be created so that bug fixes may be applied to the last version. Deprecated methods may be removed. What are the coding conventions for Xerces-C++?   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 Xerces-C++. When committing files or providing patches please keep them in mind: All classes should have a constructor, destructor, assignment operator and copy constructor to avoid compiler generated default versions of these. If a class contains only static methods, only a private constructor is required. If a class contains any virtual methods, the destructor should be virtual. 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). If you add a catch(...) block be sure to add the following block catch(const OutOfMemoryException&) { throw; } so the OutOfMemory condition does not get absorbed. 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. If a class allocates memory or is instantiated with new then it should inherit from XMemory. Use a tab size of 4 and insert them as spaces instead of keeping tabs. The code is written to be platform independent. Platform specific code should only be in the util/Platforms directory. 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. In general, code should be documented with comments. Use JavaDoc tags to describe methods. Copyright © 2003 The Apache Software Foundation. All Rights Reserved.

---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]