[llvm-dev] Explicitly spelling out the lack of stability for the C++ API in the Developer Policy?

[Mehdi AMINI via llvm-dev]

On Fri, Jul 24, 2020 at 9:35 AM Nicolai Hähnle <nhaehnle at gmail.com> wrote:

> On Fri, Jul 24, 2020 at 12:14 AM Mehdi AMINI <joker.eph at gmail.com> wrote:
> > On Thu, Jul 23, 2020 at 8:29 AM Nicolai Hähnle via llvm-dev <
> llvm-dev at lists.llvm.org> wrote:
> >> Hi Varun,
> >>
> >> On Wed, Jul 22, 2020 at 2:17 AM Varun Gandhi via llvm-dev
> >> <llvm-dev at lists.llvm.org> wrote:
> >> > * Stability Guarantees: The C++ API is does not guarantee any
> stability. Changes may be made without any notice about deprecation and
> alternate APIs for the same functionality may not be included. Downstream
> projects using the C++ API are expected to keep up with changes.
> >>
> >> I'm generally on board with this, certainly between LLVM releases, but
> >> I feel like it would be friendlier to use (potentially short-lived)
> >> deprecation as a tool for LLVM trunk.
> >>
> >> We maintain an out-of-tree compiler[0] and try to be good citizens by
> >> following LLVM trunk very closely. It is always frustrating when a
> >> very central part of LLVM (like the Builders, or Instructions) have a
> >> "flag-day" change, where our frontend must be changed in a way where
> >> the new version doesn't work with LLVM trunk that is even a few days
> >> old, and the old version doesn't work with current LLVM trunk.
> >>
> >> In many, many cases it is almost zero effort for the person making the
> >> chance in LLVM to split it up into a sequence of logical changes:
> >>
> >> 1) Add the new API.
> >> 2) Use it in llvm-project.
> >> 3) Add LLVM_ATTRIBUTE_DEPRECATED to the old API.
> >> 4) Remove the old API.
> >>
> >> 1-3 could be in a single commit, but having a few weeks between them
> >> and point 4 helps _massively_.
> >
> >
> > I don't see this as a "almost zero effort", I see this as a potentially
> *heavy* effort actually.
>
> What do you base this belief on?
>

The experience of refactoring some large components in LLVM, contrasted
with working on other codebases where I couldn't actually do this just like
in LLVM and so we just didn't do it because the change in cost/benefit.


>
>
> > I am also fairly wary of the side-effect of such expectation in that it
> will:
> > - discourage refactoring / cleanup, leading to an overall more
> cumbersome/convoluted  API surface and overall codebase.
> > - encourage to "work-around" the process by creating duplication of
> features because designing around deprecation is "work".
>
> The single most discouraging thing about refactoring / cleanup in LLVM
> is that there are very, very few reviewers willing to say "Yes".
>

By increasing the amount of churn in the codebase and the number of patches
for a refactoring and the mental effort to assess what can break and what
can/can't be made


>
> Besides, I think you misunderstood: the point isn't to *forbid*
> flag-day changes. The point is to encourage thinking about how to do
> refactoring better. Sometimes a flag-day change is required, and
> that's fine, but in the vast majority of cases it isn't.
>

No I perfectly understood, I'm still not in favor of codifying an
encouragement in this direction: I'm not eager to have reviewers ask me to
change my patch to follow the scheme you describe for stability purposes.


>
> We have seen this in practice this year with the Align changes and the
> SVE changes, and it generally works well (git log -S
> LLVM_ATTRIBUTE_DEPRECATED shows the related changes -- there aren't
> many of them, but there aren't many changes with the potential of
> breaking a frontend build in the first place).
>
> I'm simply saying that we should document established practice that
> exists in the LLVM community today.


If an author *and* a reviewers agreed at the start to take this route
because it is more convenient for landing the changes: this is perfectly
fine.
I would do it if the motivation was to land the change more easily (easier
to craft, easier to review, etc.), but this isn't the same thing as
"providing stability for a fork of LLVM" (I don't believe this is just
"documenting what is an established practice today") .

-- 
Mehdi
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20200724/d6a89ab0/attachment.html>