[discuss] Versioning strategy for standards files: SAX/DOM/JAXP

[Shane Curcuru/CAM/Lotus <sh...@us.ibm.com>]

<doc>
Here's a starting proposal for better version management of the
standards-based files in xml-commons' external directory.  Although I've
passed these ideas by a few Xerces and Xalan folks, we need community
feedback on this issue.

<proposal ver="1.0" author="curcuru@apache.org">
<item num="1">Actively manage and document the file versioning strategy for
xml-commons/java/external.</item>

<item num="2">Maintain one primary 'branch' (term used loosely) of files
that specifically track and pass the appropriate TCK's for JAXP 1.1 and
related tests.  These files would be used to create a distribution of
xml-commons (and xml-apis.jar, etc.) that can be used by any products who
need to integrate with TCK or specific-server-version environments.  For
example, JDK vendors and servlet engines may wish to be J2EE 'compatible',
which probably includes passing the JAXP 1.1 TCK; this version of
xml-commons would be for them.</item>

<item num="3">Maintain one alternate 'branch' (term used loosely) of files
that are regularly updated to match the latest-and-greatest versions of any
officially shipped versions of standards files.  This version of
xml-commons would be for any other projects who simply want the latest
standards, and don't care about passing particular TCKs for whatever
reason.</item>

<item num="4">Document procedures and find volunteers to track SAX/DOM/JAXP
standards, both to ensure new versions get triaged for checkin to
xml-commons and to pass back any bugs found in Apache versions of products
to the original standards owners.</item>
</proposal>

<background>
xml-commons is an unusual project because it partially includes
externally-defined standards files - SAX/DOM/JAXP - which not only
originate outside of Apache, but are also critical to most XML processing.
It turns out that a large number of projects actually have very specific
versioning requirements, some of which are not obvious.  Thus, we should
agree upon a versioning strategy and clearly document it so that any other
Apache (or other!) projects who wish to use our code or xml-apis.jar can
have a simple and central place to get this code.

I see two main clients for our standards files:

-- JDK teams, servlet engines, J2EE containers, etc.  These groups want XML
parsing/processing, but they also need to pass a number of Sun-defined
tests to get various certifications, etc.  This is a clear need that we
haven't always been meeting in an organized fashion, partly due to resource
issues, and partly due to general confusion about how the TCK's and the
like work.  proposal/item[@num="2"] is designed to meet this need.  With
just a little bit of effort and documentation, we can easily produce
xml-commons distributions that provide this.  Once we better understand how
the TCK's work, we could even make selected fixes and updates to various
implementations of standards files (some SAX fixes come to mind) that will
still pass the TCKs (which partly only test method signatures).

-- Various other projects who simply want the latest and best of
everything.  There are plenty of projects who don't seem to care about TCK
compatibility for whatever reason, but want access to the latest versions
of files.  This would be met by proposal/item[@num="3"] which can track the
latest SAX 2.0.1 and could even make proactive fixes or updates that Apache
projects found useful, which could then be passed back in an organized
fashion to the original standards authors.

Hopefully, this could serve as a model of collaboration between multiple
Apache projects and the various external standards groups and could make
our xml projects a little cleaner, by reducing class version conflicts and
having a single set of sources for SAX/DOM/JAXP files.
</background>

<issues>
<issue num="1">Which 'branch' would be which?  Shane proposes to make a
'TCK' branch that would meet proposal/item[@num="2"] now, and perhaps would
be updated later to meet JAXP 1.2, etc.  Then the main trunk would be for
proposal/item[@num="3"].  Why?  Because the trunk already has SAX 2.0.1
checked in, and because for me the trunk should be the latest-and-greatest.
But several others have argued the reverse, so we need to get
consensus.</issue>

<issue num="2">Better understanding and procedures for which TCK's we need
to support, and exactly what they test.  I think that a number of the IBM
committers on Xerces and Xalan may be able to help cover this issue, since
some of us already have experience in this area (sadly, Shane is not one of
them yet...)</issue>

<issue num="3">Actual packaging of standards files.  xml-commons currently
produces an xml-apis.jar as per our earlier vote that includes the full
tree of SAX/DOM/JAXP files; this is used as-is by Xalan in a formal manner
and informally by other projects.  Xerces uses their own xmlParserAPIs.jar
file in a slightly separate procedure.  And a few people have come back to
the old proposal for separate dom.jar/sax.jar/jaxp.jar files.  Note: the
actual packaging is really a separate issue from versioning strategy, so
please, let's argue that one separately!</issue>

<issue num="4">Coordination with other Apache projects, both xml and
jakarta.  If we can agree on a clear strategy and document it, I'd hope to
see the majority of Apache projects that need xml processing simply get
their files from xml-commons (or thru Xerces/Xalan, of course).  This will
take some work on documenting and publicising what xml-commons produces and
some consensus building as well.  (Plus possibly getting GUMP to run two
xml-commons builds, one for each 'branch')</issue>

<issue num="5">Coordination with various dependent Apache projects,
especially for ones with GUMP runs and/or who would want to provide builds
from both 'branches' of xml-commons (one backlevel TCK one, the other
latest-and-greatest one).</issue>
</issues>

Note that this proposal only affects the xml-commons/java/external tree; it
in no way impacts the small selection of Apache-based xml utilites rooted
at xml-commons/java/src.

- Shane
</doc>

RE: [discuss] Versioning strategy for standards files: SAX/DOM/JAXP

[Gary L Peskin <ga...@firstech.com>]

Shane --

Sorry it's taken so long to respond.  I've been swamped and I'm just
going through my old emails.

It seems to me that xml-commons (everything I say refers to the external
piece of xml-commons) is basically a "service" project designed to be a
common repository of frequently used classes for use by our various
"customers".  These customers or clients are the ones that will use
whatever xml-commons produces.  So, rather than imagine what various
projects will want (although I think you've done a good job in that
regard), I think we should -start- by making a list of all of our
potential clients from inside the Apache and Sun worlds.

Then, we should send them a quick survey that asks (1) what standards
they would like, (2) what version of those standards (latest, TCK, or
some other version), and (3) how they would like that packaged (separate
jars, one big jar, etc.).

Personally, I don't really have an idea of whether people want to "mix
and match" (latest version of SAX, TCK version of JAXP) or whether
people will always want things at the same "branch".  You may have a
good feeling for this since for some of the projects but I really have
no idea how many customers we're talking about and what they'd like to
see.

I think that once we have our customer survey done, we can step back and
see how to organize the "branches".

BTW, I know that you were using the term loosely, but I don't like CVS
branches.  So, I vote that we express the branches via various
subdirectories in CVS.  Just thought I'd throw that out before I forget
it.

Let's see what our customers want and go from there.

Just my $.02.

Gary

> -----Original Message-----
> From: Shane Curcuru/Cambridge/IBM [mailto:shane_curcuru@us.ibm.com] 
> Sent: Saturday, June 29, 2002 6:40 PM
> To: commons-dev@xml.apache.org
> Subject: [discuss] Versioning strategy for standards files: 
> SAX/DOM/JAXP
> 
> 
> <doc>
> Here's a starting proposal for better version management of 
> the standards-based files in xml-commons' external directory. 
>  Although I've passed these ideas by a few Xerces and Xalan 
> folks, we need community feedback on this issue.
> 
> <proposal ver="1.0" author="curcuru@apache.org">
> <item num="1">Actively manage and document the file 
> versioning strategy for xml-commons/java/external.</item>
> 
> <item num="2">Maintain one primary 'branch' (term used 
> loosely) of files that specifically track and pass the 
> appropriate TCK's for JAXP 1.1 and related tests.  These 
> files would be used to create a distribution of xml-commons 
> (and xml-apis.jar, etc.) that can be used by any products who 
> need to integrate with TCK or specific-server-version 
> environments.  For example, JDK vendors and servlet engines 
> may wish to be J2EE 'compatible', which probably includes 
> passing the JAXP 1.1 TCK; this version of xml-commons would 
> be for them.</item>
> 
> <item num="3">Maintain one alternate 'branch' (term used 
> loosely) of files that are regularly updated to match the 
> latest-and-greatest versions of any officially shipped 
> versions of standards files.  This version of xml-commons 
> would be for any other projects who simply want the latest 
> standards, and don't care about passing particular TCKs for 
> whatever reason.</item>
> 
> <item num="4">Document procedures and find volunteers to 
> track SAX/DOM/JAXP standards, both to ensure new versions get 
> triaged for checkin to xml-commons and to pass back any bugs 
> found in Apache versions of products to the original 
> standards owners.</item> </proposal>
> 
> <background>
> xml-commons is an unusual project because it partially 
> includes externally-defined standards files - SAX/DOM/JAXP - 
> which not only originate outside of Apache, but are also 
> critical to most XML processing. It turns out that a large 
> number of projects actually have very specific versioning 
> requirements, some of which are not obvious.  Thus, we should 
> agree upon a versioning strategy and clearly document it so 
> that any other Apache (or other!) projects who wish to use 
> our code or xml-apis.jar can have a simple and central place 
> to get this code.
> 
> I see two main clients for our standards files:
> 
> -- JDK teams, servlet engines, J2EE containers, etc.  These 
> groups want XML parsing/processing, but they also need to 
> pass a number of Sun-defined tests to get various 
> certifications, etc.  This is a clear need that we haven't 
> always been meeting in an organized fashion, partly due to 
> resource issues, and partly due to general confusion about 
> how the TCK's and the like work.  proposal/item[@num="2"] is 
> designed to meet this need.  With just a little bit of effort 
> and documentation, we can easily produce xml-commons 
> distributions that provide this.  Once we better understand 
> how the TCK's work, we could even make selected fixes and 
> updates to various implementations of standards files (some 
> SAX fixes come to mind) that will still pass the TCKs (which 
> partly only test method signatures).
> 
> -- Various other projects who simply want the latest and best 
> of everything.  There are plenty of projects who don't seem 
> to care about TCK compatibility for whatever reason, but want 
> access to the latest versions of files.  This would be met by 
> proposal/item[@num="3"] which can track the latest SAX 2.0.1 
> and could even make proactive fixes or updates that Apache 
> projects found useful, which could then be passed back in an 
> organized fashion to the original standards authors.
> 
> Hopefully, this could serve as a model of collaboration 
> between multiple Apache projects and the various external 
> standards groups and could make our xml projects a little 
> cleaner, by reducing class version conflicts and having a 
> single set of sources for SAX/DOM/JAXP files. </background>
> 
> <issues>
> <issue num="1">Which 'branch' would be which?  Shane proposes 
> to make a 'TCK' branch that would meet 
> proposal/item[@num="2"] now, and perhaps would be updated 
> later to meet JAXP 1.2, etc.  Then the main trunk would be 
> for proposal/item[@num="3"].  Why?  Because the trunk already 
> has SAX 2.0.1 checked in, and because for me the trunk should 
> be the latest-and-greatest. But several others have argued 
> the reverse, so we need to get consensus.</issue>
> 
> <issue num="2">Better understanding and procedures for which 
> TCK's we need to support, and exactly what they test.  I 
> think that a number of the IBM committers on Xerces and Xalan 
> may be able to help cover this issue, since some of us 
> already have experience in this area (sadly, Shane is not one 
> of them yet...)</issue>
> 
> <issue num="3">Actual packaging of standards files.  
> xml-commons currently produces an xml-apis.jar as per our 
> earlier vote that includes the full tree of SAX/DOM/JAXP 
> files; this is used as-is by Xalan in a formal manner and 
> informally by other projects.  Xerces uses their own 
> xmlParserAPIs.jar file in a slightly separate procedure.  And 
> a few people have come back to the old proposal for separate 
> dom.jar/sax.jar/jaxp.jar files.  Note: the actual packaging 
> is really a separate issue from versioning strategy, so 
> please, let's argue that one separately!</issue>
> 
> <issue num="4">Coordination with other Apache projects, both 
> xml and jakarta.  If we can agree on a clear strategy and 
> document it, I'd hope to see the majority of Apache projects 
> that need xml processing simply get their files from 
> xml-commons (or thru Xerces/Xalan, of course).  This will 
> take some work on documenting and publicising what 
> xml-commons produces and some consensus building as well.  
> (Plus possibly getting GUMP to run two xml-commons builds, 
> one for each 'branch')</issue>
> 
> <issue num="5">Coordination with various dependent Apache 
> projects, especially for ones with GUMP runs and/or who would 
> want to provide builds from both 'branches' of xml-commons 
> (one backlevel TCK one, the other latest-and-greatest 
> one).</issue> </issues>
> 
> Note that this proposal only affects the 
> xml-commons/java/external tree; it in no way impacts the 
> small selection of Apache-based xml utilites rooted at 
> xml-commons/java/src.
> 
> - Shane
> </doc>
> 
> 
>