John Peacock wrote:
> THE PROBLEM:
>
> The laudable notion of providing a strong API compatibility guarantees
> needs to be matched with an equally strong, conscious decision of what
> exactly constitutes the Public API. Just making every function that is
> used by more than one set of libraries part of the Public API isn't
> design; it's accretion.
You make a good point. Before version 1.0 the bug fixing and basic features
were critical, and while people did take care with API design I think there was
not enough collective effort available to do such a strong design as you
recommend. Now that we are working our way through 1.x versions it seems like
a good time to consider your advice.
> The function that I am having a problem with,
> svn_subst_copy_and_translate, is truly a low level function that
> requires specific setup before being called. It is a poor candidate for
> a public API, since to use it in third party code would require
> duplicating much of one of the already existing higher level functions.
I haven't looked at this particular issue, but if it is like you say, I would
be willing to support you in improving the situation.
> THE PROPOSAL:
>
> Before 2.0 comes out, I believe that there needs to be a much stronger
> commitment to providing an appropriate Public API, which does not
> consist of every single function in all libraries that isn't internal to
> that library.
[...]
> I would even go so far as to argue that the Public API should be made as
> small as possible for 2.0 (constituting barely more than would already
> be covered by known third-party code). It is easy to add to the Public
> API in minor releases, but it is impossible to remove anything except
> for Major releases. With a well designed program, there should be a
> limited number of entry points to prevent needless duplication of code.
> This is something that I think that Subversion 2.0 can strive to achieve.
That's a very good principle. Whether we can achieve it depends on (1) the
will to do so, and (2) the time and energy, which is where you could help us.
> The second part of this is that I believe it should be a mandatory step
> before each 1.x release to have a formal discussion of API changes,
> including (as much as possible) an examination of outstanding patches
> which make changes to the same function signatures. If this had
> happened before 1.1, I would have made much more effect to get my
> patches included. Since we are following this procedure for updating
> the API in situ, we should consciously decide that making a change now
> may preclude something else which isn't quite ready yet, until the next
> major release.
I don't follow that last sentence. By "this" procedure I take it you mean the
procedure that we are currently following. Are you saying that because
svn_subst_copy_and_translate has been modified in v1.1, you will not be able to
modify it again until major version 2? (Or did you mean minor version 1.2?)
In either case, that's false. (By "modify" I mean "deprecate and replace".)
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Mon Nov 15 18:40:51 2004