What constitutes a true API change

[Jim Jagielski <ji...@jaguNET.com>]

Specifically, let's say I wanted to change the arguments for
update_child_status() and add another parameter to that... It's
_possible_ but unlikely that outside modules may need to be aware of
that change, but it's also possible some would (for some reason)...
So would that be an API change?
-- 
====================================================================
      Jim Jagielski            |       jaguNET Access Services
     jim@jaguNET.com           |       http://www.jaguNET.com/
            "Look at me! I'm wearing a cardboard belt!"

Re: What constitutes a true API change

[Alexei Kosut <ak...@organic.com>]

On Mon, 7 Jul 1997, Jim Jagielski wrote:

> Specifically, let's say I wanted to change the arguments for
> update_child_status() and add another parameter to that... It's
> _possible_ but unlikely that outside modules may need to be aware of
> that change, but it's also possible some would (for some reason)...
> So would that be an API change?

It's an API change if it affects an API function, structure, variable,
etc... Of course, we don't have a complete published spec for the API, so
sometimes this is hard to tell. update_child_status() doesn't seem like
something a module should be calling, does it? I'd say it's not part of
the module API.

-- Alexei Kosut <ak...@organic.com>

Re: What constitutes a true API change

[Alexei Kosut <ak...@organic.com>]

On Mon, 7 Jul 1997, Rasmus Lerdorf wrote:

> > Specifically, let's say I wanted to change the arguments for
> > update_child_status() and add another parameter to that... It's
> > _possible_ but unlikely that outside modules may need to be aware of
> > that change, but it's also possible some would (for some reason)...
> > So would that be an API change?
> 
> Any change, no matter how trivial, which could in any way affect a module
> should be accompanied by a bumb of the MODULE_MAGIC_NUMBER.  I can't count
> the number of times that the API has changed without the
> MODULE_MAGIC_NUMBER getting bumped and thus affecting me.

The question really is what "the API" is. I agree that any change to "the
API," no matter how trivial, should be recorded with a change of the
number. However, even if a module is using something, if it's not part of
"the API," it should not.

Again, the question is what the API constitutes. One of the Apache 2.0
plans is to completely, 100%, document the sucker. Until then, wing it.
IMHO, we should use common sense and ask "was this function intended to be
possibly used by a module?" In the current case, I do believe the answer
is no. There are some cases (e.g., rputs()) where the answer is defenitely
yes. And there are some cases where the answer is vauge.

Oh, I do think it's desirable to change functions and such as little as
possible, especially those that are part of "the API," even internal
functions that are used throughout Apache should probably change in form
only when neccessary; although the current model of development requires
that pretty much every module be recompiled for new versions of Apache,
it'd nice to keep source backwards compatibility. AFAIK, there's only one
case between 0.8 and 1.2 where modules are not source compatible, and
that's the *_client_block() stuff. 

BTW, that's not to say that every 1.2 module will work with 0.8; the 1.2
API has a lot more than the 0.8 one, but unless it gets input from the
client, every 0.8 module should work just fine with 1.2.

-- Alexei Kosut <ak...@organic.com>

Re: What constitutes a true API change

[Rasmus Lerdorf <ra...@lerdorf.on.ca>]

> Specifically, let's say I wanted to change the arguments for
> update_child_status() and add another parameter to that... It's
> _possible_ but unlikely that outside modules may need to be aware of
> that change, but it's also possible some would (for some reason)...
> So would that be an API change?

Any change, no matter how trivial, which could in any way affect a module
should be accompanied by a bumb of the MODULE_MAGIC_NUMBER.  I can't count
the number of times that the API has changed without the
MODULE_MAGIC_NUMBER getting bumped and thus affecting me.

-Rasmus