Re: API review for 1.11; do we need to mark new APIs as experimental?

In order to strike a balance between:

* Developing new features across the more frequent release
  schedule

* Allowing developers to offer these features early, and users to
  opt in to them

* Avoiding bricking a program as described by Daniel (program
  fails to start after DLLs are upgraded)

* Avoiding the hilarity scenario described by Greg (an API with
  formerly three parameters now takes five. Two of these will be
  undefined values from the stack.

* Avoiding keeping every defunct experimental API in the
  namespace forever

* (Did I miss anything else that should be in this list?)

I suggest the following:

* When an experimental API is declared stable:

  It is moved to the stable namespace. The experimental name is
  kept as an alias for the duration of that major version (e.g.,
  Subversion 1.x).

* When an experimental API is declared defunct:

  The Subversion project should define, as part of its API/ABI
  stability rules, a length of time after which defunct
  experimental APIs are removed.

  During that length of time, the function unconditionally returns
  an error (whichever error code that ends up being) and produces a
  compile-time deprecation warning, which lists the date.

  All such APIs are kept in a single source file, sorted by their
  scheduled destruction date. That significantly reduces the burden
  of maintenance and opens up an opportunity to automate the
  process.

  The next release after that date will not contain the removed
  APIs.

  I suggest one year as the length of time.

* When an experimental API changes (Greg's scenario), the names
  are changed to protect the innocent, and the old name is treated
  the same as a defunct experimental API described above.

Clients that use experimental APIs *should* implement the pattern
of requiring the user to opt in (e.g., by checking a box in a
preference dialog) and notify the user that this feature may break
or be removed in the near future. This should be stated in
Subversion's docs for downstream developers' consideration.

Rationale: That gives downstream developers, OS distributors,
system administrators, and end users a reasonable window of time
during which client and library upgrades will not break each other;
it provides a defined expectation that all parties can plan
against; and it avoids forever accumulating a perpetually growing
list of defunct APIs.
Received on 2018-09-17 16:49:32 CEST