You are viewing a plain text version of this content. The canonical link for it is here.
Posted to c-dev@xerces.apache.org by "Jason E. Stewart" <ja...@openinformatics.com> on 2001/11/03 17:13:53 UTC
API Stability request
Hey Tinny and IBM team,
The last month or so has been a real pain in my butt for
Xerces-Perl.
The public API changed frequently, and that was mostly because of the
addition of cool new features which we all wanted to see. However it
was totally undocumented, so there was little or no way for me to know
that you had removed API methods or added any new ones.
Currently, Xerces-C has no information about what has changed between
one version to the next, except for:
http://xml.apache.org/xerces-c/releases.html
It would be a great help to me (and perhaps the python port as well),
if anyone who checks code into CVS that modifies the API could write
this list and (briefly) indicate what API methods were affected. And
then when a new release is made, we can easily compile a list of the
API changes between versions.
Thanks again for all your excellent work,
jas.
PS.
I suppose that I could subscribe to the CVS commit list, but this is
much more low level than I want, and I would still have to go
grovelling through the commit logs to find the info I want.
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-c-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-c-dev-help@xml.apache.org
Re: API Stability request
Posted by "Jason E. Stewart" <ja...@openinformatics.com>.
"Tinny Ng" <tn...@ca.ibm.com> writes:
> Sounds ok. And besides posted in the mailing list, all these should
> be documented in the migration guide when a release is out.
Great!!
> BTW since you said you've gone through all these trouble while porting the past
> release, so do you have such information gathered? If so, can you put such
> information in the migration guide (doc/migrate.xml)?
Sorry :-(
I never wrote it down. Once upon a time I maintained a private set of
header files, and so I had to track changes. Some of the info could be
gotten from my CVS logs, but not much. Probably simpler to just go
through CVS logs of Xerces-C header files.
jas.
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-c-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-c-dev-help@xml.apache.org
Re: API Stability request
Posted by Tinny Ng <tn...@ca.ibm.com>.
Jason,
Sounds ok. And besides posted in the mailing list, all these should be
documented in the migration guide when a release is out.
BTW since you said you've gone through all these trouble while porting the past
release, so do you have such information gathered? If so, can you put such
information in the migration guide (doc/migrate.xml)?
Tinny
"Jason E. Stewart" wrote:
> "Tinny Ng" <tn...@ca.ibm.com> writes:
>
> > For "public API", do you mean all those API that are defined as
> > "public:" in the class, or those API that are externally documented
> > in http://xml.apache.org/xerces-c/apiDocs/classes.html?
> >
> > If latter (documented API), then our team has been "trying" to do so
> > already. Though sometimes forget ;-), at least stablizing those publicly
> > documented API is our objective. And yes we can document any changes in
> > the migration guide, or deprecate them for a couple of releases before
> > actual removal.
>
> Hey Tinny,
>
> Yes, I intended the documented API in apiDocs. The purpose of my email
> was not to chastise anyone, but merely to point out that it would be a
> HUGE help for me, and to encourage all involved to document the
> changes.
>
> I heartily approve of the idea of depricating interfaces for a couple
> of releases. Can when agree on this one as of today? I find that
> application developers get thoroughly ticked off when they upgrade
> code to newer library versions and their existing code stops
> working. By depricating, we give them a warning of things to come.
>
> So that gives us three situations that need documenting:
>
> * addition of new API methods/classes: Should be announced on the
> xerces-c-dev list when committed to CVS? This is the one that
> gave me trouble in the past. This would alert me that I can no
> longer use the CVS code to make stable releases from, and that I
> need to keep track of which branch I work with. Until that happens
> it's simpler just to use a single tree.
>
> * removal of API methods/classes: Should only be done in next major
> release XX months after it was depricated. 6 months would be fine by
> me. I think perl uses 12 months as its guideline.
>
> * modification of API methods/classes: Does this ever happen? New
> parameters, or modification of parameter types/return values? If so,
> I would be really grateful if this was posted to xerces-c-dev when
> committed to CVS.
>
> Any other thoughts?
>
> Thanks!
> jas.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: xerces-c-dev-unsubscribe@xml.apache.org
> For additional commands, e-mail: xerces-c-dev-help@xml.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-c-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-c-dev-help@xml.apache.org
Re: API Stability request
Posted by "Jason E. Stewart" <ja...@openinformatics.com>.
"Tinny Ng" <tn...@ca.ibm.com> writes:
> For "public API", do you mean all those API that are defined as
> "public:" in the class, or those API that are externally documented
> in http://xml.apache.org/xerces-c/apiDocs/classes.html?
>
> If latter (documented API), then our team has been "trying" to do so
> already. Though sometimes forget ;-), at least stablizing those publicly
> documented API is our objective. And yes we can document any changes in
> the migration guide, or deprecate them for a couple of releases before
> actual removal.
Hey Tinny,
Yes, I intended the documented API in apiDocs. The purpose of my email
was not to chastise anyone, but merely to point out that it would be a
HUGE help for me, and to encourage all involved to document the
changes.
I heartily approve of the idea of depricating interfaces for a couple
of releases. Can when agree on this one as of today? I find that
application developers get thoroughly ticked off when they upgrade
code to newer library versions and their existing code stops
working. By depricating, we give them a warning of things to come.
So that gives us three situations that need documenting:
* addition of new API methods/classes: Should be announced on the
xerces-c-dev list when committed to CVS? This is the one that
gave me trouble in the past. This would alert me that I can no
longer use the CVS code to make stable releases from, and that I
need to keep track of which branch I work with. Until that happens
it's simpler just to use a single tree.
* removal of API methods/classes: Should only be done in next major
release XX months after it was depricated. 6 months would be fine by
me. I think perl uses 12 months as its guideline.
* modification of API methods/classes: Does this ever happen? New
parameters, or modification of parameter types/return values? If so,
I would be really grateful if this was posted to xerces-c-dev when
committed to CVS.
Any other thoughts?
Thanks!
jas.
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-c-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-c-dev-help@xml.apache.org
Re: API Stability request
Posted by Tinny Ng <tn...@ca.ibm.com>.
Jason,
For "public API", do you mean all those API that are defined as "public:"
in the class, or those API that are externally documented in
http://xml.apache.org/xerces-c/apiDocs/classes.html?
If latter (documented API), then our team has been "trying" to do so
already. Though sometimes forget ;-), at least stablizing those publicly
documented API is our objective. And yes we can document any changes in
the migration guide, or deprecate them for a couple of releases before
actual removal.
But if you mean all those "public:" class member functions, then the scope
is much bigger and involves more effort which not easy to afford.... And
user is not encouraged to use those internal undocumented APIs directly.
Tinny
"Jason E. Stewart" wrote:
> Hey Tinny and IBM team,
>
> The last month or so has been a real pain in my butt for
> Xerces-Perl.
>
> The public API changed frequently, and that was mostly because of the
> addition of cool new features which we all wanted to see. However it
> was totally undocumented, so there was little or no way for me to know
> that you had removed API methods or added any new ones.
>
> Currently, Xerces-C has no information about what has changed between
> one version to the next, except for:
>
> http://xml.apache.org/xerces-c/releases.html
>
> It would be a great help to me (and perhaps the python port as well),
> if anyone who checks code into CVS that modifies the API could write
> this list and (briefly) indicate what API methods were affected. And
> then when a new release is made, we can easily compile a list of the
> API changes between versions.
>
> Thanks again for all your excellent work,
> jas.
>
> PS.
>
> I suppose that I could subscribe to the CVS commit list, but this is
> much more low level than I want, and I would still have to go
> grovelling through the commit logs to find the info I want.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: xerces-c-dev-unsubscribe@xml.apache.org
> For additional commands, e-mail: xerces-c-dev-help@xml.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-c-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-c-dev-help@xml.apache.org