As the community forms, we need to formalize these guidelines, especially to differentiate
'requirements' from suggested 'guidelines'.
Shane's starting proposals:
xml-commons is an unusual project in several ways.
First, it encompasses two kinds of code: external and apache.
Secondly,
xml-commons mainly focuses on providing code and services to other
xml.apache.org projects instead of shipping it's own 'standalone' project.
Third, it will also tend to be more focused on smaller, interoperable modules of
code and a very high degree of stability.
In some ways, the forming of
xml-commons is the seed of a catalyst to improve cross-project coordination
throughout xml.apache.org. One potential goal is to get all xml.apache.org
projects to take their xml standards oriented code - like DOM, SAX and JAXP -
from specific marked builds of xml-commons, instead of each project
using different versions of these files.
External code: xml-commons will serve as an Apache-controlled
copy of externally-defined standards-based files. This way, we can try
to manage common versions of these important xml standards-based files
and interfaces. Read more here.
Apache code: xml-commons will serve as a shared repository for
common xml-oriented utilities or building blocks that several other
xml.apache.org projects wish to use. The first example is org.apache.env.Which,
and environment checking utility that scans your environment and reports common
versions of xml-related files. The next likely submission is an entity resolver
that could be plugged into any xml parsing, transforming, or processing
project. Read more here.
Directory tree (proposed)
xml-commons/
README.html - this file
build.xml - overall build file for top-level items
xdocs/ - top-level xml format docs about this project itself and our guidelines
(in whatever format xml.apache.org uses for site)
docs/ - (not checked in) html format docs created by 'build docs' from xdocs
java/ - root of all java-related files
external/ - src root of all source files in java that come from external sources
for example: the DOM, SAX, and JAXP files
org/xml/sax/*
org/w3c/dom/*
javax/xml/*
external/build.xml - Ant build file for all external sources
xdocs/ - xml format docs describing any java files, as needed
{name}.xml - Ant build file for Apache-defined subproject(s)
future: resolver.xml: for Norm Walsh's entity resolver submission, when done
src/ - root of Apache-defined Java code
src/org/apache/... etc
which.xml - Ant build file for org.apache.env.Which utility
c/ - root of all C/C++ related files
external/ - root of all externally-owned C/C++ sources
perl/ - root of all Perl related files
etc.
- We should consider adopting those guidelines from the jakarta-commons
project that make sense for our xml projects - keeping in mind that both the kind of
projects we build are different than jakarta, and some of our goals are a
little bit different.
- Dicsussion and buy-in should happen on the project mailing list
before checking in new modules.
- New modules generally shouldn't go in until at least two separate
other projects express interest in using the module. I think this is an
important difference from jakarta-commons that makes sense in our world.
I.e. I'd rather not just throw something in because it seems like it might
be useful, I'd rather only put things in that we know will be shared among
multiple projects.
- The xml-commons community should come up with guidelines for other
xml.apache.org subprojects to use the code that commons has. I.e. suggestions
and ways to package this code vis-a-vis the other project's code in a common way.
- Other shared xml.apache.org guidelines? Like documentation format, testing techniques/policies, etc.