You are viewing a plain text version of this content. The canonical link for it is here.
Posted to j-dev@xerces.apache.org by Andy Clark <an...@apache.org> on 2002/05/16 17:40:21 UTC
Suggestions for New Committers
I think it's great that more Sun people are coming onboard
to help out with the project. However, as more new people
join in the active development of the code (which means
actually committing changes directly to CVS) I think we
should have some guidelines to help new people and ensure
the quality and integrity of the source tree.
Unfortunately, we don't have any documentation specifically
written for the developers of Xerces. This is something we
definitely need to write, especially once we start creating
sub-projects within Xerces. The Jakarta folks have done a
good job with their documentation and we should improve ours
as well. But this will have to wait until someone has the
time (and energy) for this task. I may start it once I free
up some time...
Anyway, back to the point of this message. I want to offer
a few helpful suggestions to Pavani and all new committers
in general.
When someone approaches new and unfamiliar source it's not
uncommon to make a few mistakes. Don't worry too much about
it because we've all been there. And the rest of the people
working on the code can help out answering questions, etc.
But with committer access comes a lot more responsibility.
Because you will have direct access to the source tree, you
need to be twice as alert about what effects your changes
have on the rest of the source. Sometimes seemingly simple
changes can break other components that may not be so easy
to understand or fix. So before jumping in there and
committing a lot of code, try to remember the following
points:
* Whenever making changes that affect multiple components,
the changes need to be tested *thouroughly*. This
generally means:
1) performing a "build clean all"
2) running conformance tests
3) running any other applicable tests
And this needs to be done BEFORE committing the change.
* If a fix or additional feature requires an API change,
no matter how small you think it is, you should always
ask the others their advice via the public mailing list.
Big changes need concensus and sometimes a vote.
* When checking in a change, the commit message needs
to be extremely descriptive. You don't have to write
a book but it should describe the problem, the
affected systems, and the solution. It's also good to
put the reporter of the bug, etc. in this message.
In addition, if the change is important enough, then
the change should be documented in the docs/releases.xml
file as well. And if the change is to fix a bug that is
reported in Bugzilla, that record needs to be moved to
its proper concluding state.
* Changes should follow the established standards for the
project's source. Some of these include the following:
a) Consistant naming conventions for classes, fields,
methods, etc.
b) Properly using the XNI interface and obeying the
requirements imposed by the components implementing
those interfaces.
c) Avoid adding dependencies that break backwards
compatibility or the ability to layer the parser
implementation freely.
* ...etc...
I haven't listed everything that needs to be stated. This is
just what I happen to think of as I was writing this message.
But this is the kind of things that I would like to have in
our docs for current and future developers.
In short, it may take some time for a new committer to get
accustomed to the existing source and its inter-dependencies.
Therefore, it is wise to take advantage of your fellow
committers and their deeper knowledge of the source tree.
It might even be good to continue submitting your changes
through another committer as you are getting used to the
whole process.
Welcome aboard, new committers!
--
Andy Clark * andyc@apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-j-dev-help@xml.apache.org
Re: Suggestions for New Committers
Posted by Andy Clark <an...@apache.org>.
"Theodore W. Leung" wrote:
> in the spirit of 2, I've checked in a modification to build.xml that
> allows a developer to fetch a copy of the xmlconf test suite from
> sourceforge, and to then run both validating and non-validating reports
> on Xerces. Curiously enough, when I did this, I found some failures.
Arnaud is right, the "standard" test suite contains errors.
I know that I had to fix some bugs in the XML script used to
drive the conformance test as well as repair the damage
caused by CVS/tar to newlines, etc. on the expected output.
Hopefully this situation will improve in the next version
of the suite.
So when I run tests, I use my augmented conformance suite
of files. And even with that I get some spurious errors. So
I run the tests twice: once before affecting a change and
again afterwards. Then I compare the results of both to see
if there are any regressions.
--
Andy Clark * andyc@apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-j-dev-help@xml.apache.org
Re: Suggestions for New Committers
Posted by "Theodore W. Leung" <tw...@sauria.com>.
On Thu, 2002-05-16 at 18:28, Arnaud Le Hors wrote:
> Theodore W. Leung wrote:
>
> > in the spirit of 2, I've checked in a modification to build.xml that
> > allows a developer to fetch a copy of the xmlconf test suite from
> > sourceforge, and to then run both validating and non-validating reports
> > on Xerces. Curiously enough, when I did this, I found some failures.
>
> Although I can't give a definitive answer on all the failures, some of
> them come from the fact that the test suite on sourceforge has errors.
> It's the result of errors in the original distribution plus David
> Brownel's own interpretation of the XML spec.
Hmm.
Okay. It looks like some of the IBM tests are failing..
here's what it said:
http://xml.apache.org/~twl/report.html
>
> The good news is that the work on the XML Test Suite has been taken over
> by the W3C XML Core WG, which also maintains the XML spec and its
> errata, with the help of NIST. A new version of the test suite should be
> released very soon.
That sounds good. Can you post when that happens so that I can update
the build file?
Also, I noticed that W3C is doing a Schema test suite, but when I went
to download it it seemed poorly organized and hard to use in an
automated setting. Is this actively being worked on?
Ted
> --
> Arnaud Le Hors - IBM, XML Standards Strategy Group / W3C AC Rep.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
> For additional commands, e-mail: xerces-j-dev-help@xml.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-j-dev-help@xml.apache.org
Re: Suggestions for New Committers
Posted by Arnaud Le Hors <le...@us.ibm.com>.
Theodore W. Leung wrote:
> in the spirit of 2, I've checked in a modification to build.xml that
> allows a developer to fetch a copy of the xmlconf test suite from
> sourceforge, and to then run both validating and non-validating reports
> on Xerces. Curiously enough, when I did this, I found some failures.
Although I can't give a definitive answer on all the failures, some of
them come from the fact that the test suite on sourceforge has errors.
It's the result of errors in the original distribution plus David
Brownel's own interpretation of the XML spec.
The good news is that the work on the XML Test Suite has been taken over
by the W3C XML Core WG, which also maintains the XML spec and its
errata, with the help of NIST. A new version of the test suite should be
released very soon.
--
Arnaud Le Hors - IBM, XML Standards Strategy Group / W3C AC Rep.
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-j-dev-help@xml.apache.org
Re: Suggestions for New Committers
Posted by "Theodore W. Leung" <tw...@sauria.com>.
On Thu, 2002-05-16 at 08:40, Andy Clark wrote:
>
> * Whenever making changes that affect multiple components,
> the changes need to be tested *thouroughly*. This
> generally means:
>
> 1) performing a "build clean all"
> 2) running conformance tests
> 3) running any other applicable tests
>
> And this needs to be done BEFORE committing the change.
>
in the spirit of 2, I've checked in a modification to build.xml that
allows a developer to fetch a copy of the xmlconf test suite from
sourceforge, and to then run both validating and non-validating reports
on Xerces. Curiously enough, when I did this, I found some failures.
Also at the moment, the report files begin with garbage because ant
captures both stderr and stdout to the same file, and the conformance
test suite driver doesn't have a way to specify an output file for the
test.
Ted
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-j-dev-help@xml.apache.org