Julian Foad wrote on Thu, Sep 13, 2018 at 09:44:47 +0100:
> Daniel Shahaf wrote:
> > Julian Foad wrote:
> >> We recently decided that only APIs released in an LTS release will be
> >> subject to our compatibility guarantees. As 1.11 is not an LTS release,
> >> the above APIs will not be subject to those guarantees (until they
> >> appear in an LTS).
> >>
> >> Do we need to do anything in the source code to emphasize that, for the
> >> ones that are not already marked 'experimental'? If so, what? Mark them
> >> 'experimental' in addition to their existing annotations (which probably
> >> would mean we'd want to turn off the warnings about use of experimental
> >> APIs in our own builds), or something else?
> >
> > I'm not sure all of these APIs need to be marked experimental. For
> > example, svn_client_layout_list() is new functionality that we might not
> > want to support forever, but the 'pretty_print_mergeinfo' change sounds
> > pretty safe.
>
> How do you square that with the proposal in the thread "API compatibility promises in light of biannual releases" where you replied "+1" to the following?
>
I'm trying to strike a balance between two extremes.
On the one hand, under our compatibility rules, releasing an API is a
one-way street: it compels us to support it indefinitely. On the other
hand, if an API _is_ stable, we needn't sit on the formality of waiting
for an LTS release to declare it so.
Case in point, the addition of PRETTY_PRINT_MERGEINFO to
svn_client_diff7(). The new behaviour is to *disable* a special-case
code path; I can hardly see a situation in which continuing to support
such a disabling would be a maintenance burden, and therefore, I see no
reason why svn_client_diff7() shouldn't be released under the standard
compatibility promise we've used through 1.10.
Second case in point, the shelving logic. In 1.10 and 1.11 we're
releasing early forms of shelving for consumption by users and API
consumers. We're hoping this will result in feedback that will allow
us to write the API better the first time around — but this is only
possible if what we *are* releasing in 1.10 and 1.11 doesn't get the
same compatibility promises as everything else.
Frequent minor releases are a good thing, and releasing APIs under
reduced compatibility promises at first (and strengthening the promises
subsequently) is also a good thing, but I think I'm coming to agree with
what Brane said downthread, that these two good things should neither be
conflated nor coupled. Some releases receive bugfixes for ×4 times as
long as others. Some releases see APIs being bestowed upon the "Will be
supported through the end of time^Wthe 1.x line" badge (either new APIs,
or ones that were previously released under reduced forward compatibility
promises). These can and should be two independent aspects of a release,
shouldn't they?
Thanks for asking.
To be concrete, I propose that we have exactly two kinds of public APIs:
[[[
- Standard public APIs are supported through the end of the major
release line (1.x, 2.x, etc) they appear in.
- Experimental public APIs are named svn_x_* and are supported through
the end of the minor release line (1.11.x, 1.12.x, etc) they appear
in. A particular API may make stronger promises in its docstring, but
not weaker. (If we ever need to make even weaker a promise than this,
APIs covered by it should be in a different namespace.)
Experimental public APIs may be graduated to non-experimental status
at any minor release.
]]]
And I further propose that we implement this convention on the 1.11.x
branch before 1.11.0.
Thanks for asking.
Cheers,
Daniel
> > However, a process of marking all new APIs as experimental in
> > regular releases, and ensuring we review them for LTS releases,
> > might be a good way to satisfy both Semantic Versioning and
> > experimental APIs.
>
> There, the proposal was that *all* new APIs (which I would assume
> includes revved ones) should be regarded as experimental and marked as
> such until "blessed" by appearing in an LTS release. Are we saying now
> that they need not be specifically marked if we feel they are pretty
> safe? If we say that, then marking specific APIs as "experimental" in
> a regular release signifies only that we consider them more
> experimental (less stable) than others.
>
> That might be fine. Anyone developing against a regular release is
> necessarily developing against new (experimental) APIs, so maybe no
> explicit warning mechanism is necessary.
>
> -- - Julian
Received on 2018-09-14 14:35:37 CEST