[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: RFC: API Compatibility Concerns

From: John Peacock <jpeacock_at_rowman.com>
Date: 2004-11-15 19:45:01 CET

Greg Hudson wrote:
> No, it's a design. It's a design you don't like, and it's not a perfect
> design, but it's not "accretion."

I'm arguing that "all functions which have to be called from multiple library
must be part of the public API for all code" isn't a /good/ design philosophy,
that's true. If I write some great new code which has to be called from three
different libraries, even though it is very low level, I currently have to place
that in the Public API, because there is no middle ground. And once it is in
the Public API, it is frozen until the next major release (modulo API rev).
Since a function can only be Public or Internal, it to a form of API creep and
it will make it that much more difficult to simplify the API for 2.0.

>
>
>>The function that I am having a problem with, svn_subst_copy_and_translate, is
>
> I think if that were really true, we wouldn't be using it in three
> places in libsvn_client.

But if you look at exactly where it is used, you see that there is a lot of
overhead in preparation to use it:

        commit.c:send_file_contents() - internal function
        export.c:copy_versioned_files() - Public API
        export.c:close_file() - internal function

and the fact that two out of the three calls here are private makes it even more
evident that svn_subst_copy_and_translate() is really a helper function for the
libraries themselves, rather than a high-level API.

But I don't want to argue this specific instance here; it was more as an example
of the larger question:

Does the Subversion project want to continue to add to the API without limit or
should we begin the process now of redesigning the API in preparation for 2.0?

I don't think that we would be violating the API promises now by deciding that
new functions added to the code are not Public unless we say they are. Use the
double underscore to mean Private (core library usage only), not just for
intralibrary functions. Don't add any new API to the Public list unless it
significantly encapsulates valuable work.

>
>
>>If I were to bring my patches up to date now, would I get grief from people that
>>adding a third iteration of svn_subst_copy_and_translate would "muddy" the API.
>
>
> There's no need for concern here; we've been quite willing to rev APIs,
> and we've never shot anything down because we didn't want to rev an API.

Good! That's exactly the kind of strong support of the policy I was looking
for. I'll start a new thread on your other thoughts about the keywords-as-hash
patch itself.

John

-- 
John Peacock
Director of Information Research and Technology
Rowman & Littlefield Publishing Group
4720 Boston Way
Lanham, MD 20706
301-459-3366 x.5010
fax 301-429-5747
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Mon Nov 15 19:45:12 2004

This is an archived mail posted to the Subversion Dev mailing list.