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

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>

On Jul 24, 2020, at 9:50 AM, Mehdi AMINI via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 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.
I can see both sides of this.  Deprecation has a lot of value that Nicolai
points out and some people do use it.  I don’t think it is possible to get to
perfect “deprecation cycles” and even outside perfection an overly-broad
application of this would just be expensive.  Some things (e.g. core IR) simply
matter more than others.

Perhaps a way too slice this is to phrase it along the lines of:

1) There is no guarantee.
2) That said, for core IR changes it is nice to stage them for XYZ reasons.
3) If you do so, “this is the right way".

-Chris
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200726/b9256d8a/attachment.html>

On Sun, Jul 26, 2020 at 11:40 PM Chris Lattner <clattner at nondot.org>
wrote:
>
> On Jul 24, 2020, at 9:50 AM, Mehdi AMINI via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
>>
>> 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.
>
>
> I can see both sides of this.  Deprecation has a lot of value that Nicolai
points out and some people do use it.  I don’t think it is possible to get to
perfect “deprecation cycles” and even outside perfection an overly-broad
application of this would just be expensive.  Some things (e.g. core IR) simply
matter more than others.
>
> Perhaps a way too slice this is to phrase it along the lines of:
>
> 1) There is no guarantee.
> 2) That said, for core IR changes it is nice to stage them for XYZ reasons.
> 3) If you do so, “this is the right way".
That sounds good to me.

Cheers,
Nicolai

>
> -Chris


-- 
Lerne, wie die Welt wirklich ist,
aber vergiss niemals, wie sie sein sollte.