Timetables for interface deprecation/deletion

Brian Somers · *nix forums beginner Joined: 04 Apr 2002 Posts: 14

I think this sort of approach is good. We should introduce this sort
of thing (as a section in our man pages), but (as Poul-Henning says) we
shouldn't let it prevail against common sense.

Interfaces such as those that ps(1) and the like use should have a
classification of ``private'', meaning that you're not allowed to use it
- even if it's documented (which it generally shouldn't be).

However the stuff in places like libutil should be documented to a
degree that people know whether they should use them or not.

I don't think a major release number's worth of support is too much to
ask for. In fact I'd say this sort of thing should be a major
consideration for any commercial body deciding to go with FreeBSD.

On Tue, 18 Jun 2002 22:55:23 +0100, Nik Clayton wrote:

Poul-Henning Kamp · *nix forums Guru Joined: 21 Mar 2002 Posts: 436

I've read the entire thread now.

I'm sure this is well intended.

But I am firmly against such a sweeping use of "red tape" as it
will make forward progress practically impossible:

KSE for instance would not be possible because it changes the API
so that old ps(1) binaries do not work.

I think we need make a considered judgement, per major release,
about what is in, what is out and what stays for compatibility
reasons, having rigid and inflexible rules on the subject is not
helpful to anybody.

This is the kind of rigid square policy-making which big companies
need to apply because they dare not delegate "good judgement" to
their development department.

This does not belong in a for-fun Open Source project.

I agree that we need to follow standards reasonably close, but we
do not need to be backwards compatible over timespans of 5 years.

--
Poul-Henning Kamp | UNIX since Zilog Zeus 3.20
phk@FreeBSD.ORG | TCP/IP since RFC 956
FreeBSD committer | BSD since 4.3-tahoe
Never attribute to malice what can adequately be explained by incompetence.

To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-arch" in the body of the message

Garrett Wollman · *nix forums addict Joined: 08 May 2002 Posts: 59

In article <20020618225523.J52976@canyon.nothing-going-on.org> you write:

Terry Lambert · *nix forums Guru Joined: 19 Mar 2002 Posts: 434

Nik Clayton wrote:

Jordan K. Hubbard · *nix forums beginner Joined: 18 Jun 2002 Posts: 4

Nik,

I'm glad you were the first one to bring this up since I'd likely have
only been accused of being self-serving if I were the one to do so. :-)

Apple is facing the very same issue with respect to "published APIs"
and making it clear which we're free to deprecate at some future date,
which are obsolete and purely for backwards compatibility (e.g. not to
be used for new code), which are purely "use at your own risk" and
which are fully supported in the sense that we'll contort ourselves
into all sorts of unnatural shapes, if and as necessary, to preserve
compatibility with them.

We've also adopted Sun's nomenclature for the macros which bracket
these APIs in various headers since we didn't see any need to reinvent
that particular wheel. I don't have the list handy right now, but it
basically defines the macro names you need to bracket the various
header definitions for the APIs you want to classify and/or restrict.
If FreeBSD's willing to go the same route, it would greatly help in
syncronizing this kind of API clean-up work between FreeBSD and Darwin.
Thoughts? I'm just looking for opinions at this stage and nobody's
talking about touching ANYTHING right now, this is just stage 1 (or
zero, depending on how you measure things).

- Jordan

On Tuesday, Jun 18, 2002, at 14:55 America/Los_Angeles, Nik Clayton
wrote:

Nik Clayton · *nix forums beginner Joined: 09 Apr 2002 Posts: 20

[ It's times like this I regret the fact that we don't have a Linus
equivalent to lay down the law ]

As FreeBSD develops, we inevitably change, adapt, and throw away old
'interfaces'.

* Library APIs
* The behaviour of command line options
* The use of certain commands
* Configuration options and mechanisms

and more.

I think the life cycle of an interface can be described as follows:

Introductory We make no guarantee this interface will be in
future versions of FreeBSD.

Stable This interface is guaranteed to exist in
all minor versions of FreeBSD corresponding with
the major version in which it exists.

Once an interface is marked 'Stable' it must go
through the 'Deprecated' and 'Obsolete' stages
before removal.

Deprecated The interface is supported, but is slated for
obsolecence in the next major release of
FreeBSD.

Obsolete The interface is not supported. It may work,
but it is not guaranteed to. The interface will
be removed in the next major version of FreeBSD.

Assuming, for the moment, that that makes sense to people, over what sort
of timescales should interfaces move from state to state?

And does the project have the will to guarantee this?

[ "Guarantee"? OK, nothing's guaranteed in an open source project. But
IMHO, there are a few things that the project should commit to. As
long as these things are appropriately documented, and decided upon --
committer vote? core declaration? -- unwillingness to commit to them
should be grounds for removal of a commit bit.

Harsh, I know. But as I mention above, we don't have a Linus-like
figure to lay down the law. ]

N
--
FreeBSD: The Power to Serve http://www.freebsd.org/ (__)
FreeBSD Documentation Project http://www.freebsd.org/docproj/ \\\'',)
\/ \ ^
--- 15B8 3FFC DDB4 34B0 AA5F 94B7 93A8 0764 2C37 E375 --- .\._/_)

Google