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 * [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
