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

The Developer Policy document (https://llvm.org/docs/DeveloperPolicy.html)
contains a Section "C API Changes". There is no corresponding section
for C++ API Changes. LLVM is somewhat different from most libraries in that the
main language is C++ but the C++ API is not guaranteed to be stable in any shape
or form from what I understand.

I think it would be useful to have a "C++ API Changes" section to
Developer Policy spelling this out. Copying the style of the C API Changes
section, it could look something like:

---
C++ API Changes

* 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.
* Release stability: The C++ API does not make any stability guarantees for the
release branch.
* Testing: Patches to the C++ API are expected to come with tests just like any
other patch.
* Including new things into the API: [TODO: I'm not sure what should go
here].
* Documentation: Changes to the C++ API are not expected to be documented in the
release notes.
---

Clang does have a page with information about its own C++ API
(https://clang.llvm.org/docs/Tooling.html) which is more informative, but I
think it would useful to have this information on the Developer Policy page for
the whole of LLVM.

Does this addition sound reasonable?

Varun
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200721/4aed1f83/attachment.html>

This sounds reasonable to me, I am generally +1 on documenting things that are
well known but not written down.

Thanks Varun!

-Chris
> On Jul 21, 2020, at 5:16 PM, Varun Gandhi via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 
> The Developer Policy document (https://llvm.org/docs/DeveloperPolicy.html
<https://llvm.org/docs/DeveloperPolicy.html>) contains a Section "C
API Changes". There is no corresponding section for C++ API Changes. LLVM
is somewhat different from most libraries in that the main language is C++ but
the C++ API is not guaranteed to be stable in any shape or form from what I
understand.
> 
> I think it would be useful to have a "C++ API Changes" section to
Developer Policy spelling this out. Copying the style of the C API Changes
section, it could look something like:
> 
> ---
> C++ API Changes
> 
> * 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.
> * Release stability: The C++ API does not make any stability guarantees for
the release branch.
> * Testing: Patches to the C++ API are expected to come with tests just like
any other patch.
> * Including new things into the API: [TODO: I'm not sure what should go
here].
> * Documentation: Changes to the C++ API are not expected to be documented
in the release notes.
> ---
> 
> Clang does have a page with information about its own C++ API
(https://clang.llvm.org/docs/Tooling.html
<https://clang.llvm.org/docs/Tooling.html>) which is more informative, but
I think it would useful to have this information on the Developer Policy page
for the whole of LLVM.
> 
> Does this addition sound reasonable?
> 
> Varun
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200722/52f6b601/attachment.html>

Something that would be good to get clarity on:

The RISC-V backend recently had a bugfix patch that got backported to the 10.0.1
branch. The original patch introduced a new virtual method in TargetLowering.h,
and the backported patch [1] was rewritten to avoid changing the ABI of
libLLVM.so.

This feels like some kind of policy decision about the C++ ABI beyond
"it's entirely unstable" - though I understand we may not want to
commit to doing this for every backported bug fix.

It would be good to understand where this line is, if we're going to clarify
the documentation.

Sam

[1]:
https://github.com/llvm/llvm-project/commit/f8e49af4f1adcf457ea32e7164a126b10357cf4f
> On 23 Jul 2020, at 4:52 am, Chris Lattner via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 
> This sounds reasonable to me, I am generally +1 on documenting things that
are well known but not written down.
> 
> Thanks Varun!
> 
> -Chris
> 
>> On Jul 21, 2020, at 5:16 PM, Varun Gandhi via llvm-dev <llvm-dev at
lists.llvm.org <mailto:llvm-dev at lists.llvm.org>> wrote:
>> 
>> The Developer Policy document
(https://llvm.org/docs/DeveloperPolicy.html
<https://llvm.org/docs/DeveloperPolicy.html>) contains a Section "C
API Changes". There is no corresponding section for C++ API Changes. LLVM
is somewhat different from most libraries in that the main language is C++ but
the C++ API is not guaranteed to be stable in any shape or form from what I
understand.
>> 
>> I think it would be useful to have a "C++ API Changes"
section to Developer Policy spelling this out. Copying the style of the C API
Changes section, it could look something like:
>> 
>> ---
>> C++ API Changes
>> 
>> * 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.
>> * Release stability: The C++ API does not make any stability guarantees
for the release branch.
>> * Testing: Patches to the C++ API are expected to come with tests just
like any other patch.
>> * Including new things into the API: [TODO: I'm not sure what
should go here].
>> * Documentation: Changes to the C++ API are not expected to be
documented in the release notes.
>> ---
>> 
>> Clang does have a page with information about its own C++ API
(https://clang.llvm.org/docs/Tooling.html
<https://clang.llvm.org/docs/Tooling.html>) which is more informative, but
I think it would useful to have this information on the Developer Policy page
for the whole of LLVM.
>> 
>> Does this addition sound reasonable?
>> 
>> Varun
>> _______________________________________________
>> LLVM Developers mailing list
>> llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>
>> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
> 
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
--
Sam Elliott
Software Team Lead
Senior Software Developer - LLVM and OpenTitan
lowRISC CIC

-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200723/7f2b7e9c/attachment.html>

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_.

It allows us to keep compiling against LLVM trunk in our CI, while one
person goes and fixes up our use of the API (which we can detect
automatically thanks to the warning or -Werror). It also makes it
easier for us to bisect regressions across such API changes.

With the alternative, where 1-4 are all in a single commit, our
integration with LLVM trunk is blocked until somebody can fix it --
which is usually as quick as 1 or 2 days, but during that time window
we don't catch any _other_ regressions in LLVM trunk that might affect
us.

So please, let's make it a common rule to use this two-step,
transactional approach to changes in APIs that are relatively "core"
(which mostly means llvm/IR, llvm/ADT, llvm/Support, perhaps with a
side of llvm/Analysis). I am perfectly fine with this rule being
broken occasionally, for changes where it would be exceedingly tricky
to do them in a non-flag-day way. But in our experience, most of the
changes that would actually affect an out-of-tree frontend aren't this
tricky.

Cheers,
Nicolai

> * Release stability: The C++ API does not make any stability guarantees for
the release branch.
> * Testing: Patches to the C++ API are expected to come with tests just like
any other patch.
> * Including new things into the API: [TODO: I'm not sure what should go
here].
> * Documentation: Changes to the C++ API are not expected to be documented
in the release notes.
> ---
>
> Clang does have a page with information about its own C++ API
(https://clang.llvm.org/docs/Tooling.html) which is more informative, but I
think it would useful to have this information on the Developer Policy page for
the whole of LLVM.
>
> Does this addition sound reasonable?
>
> Varun
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev


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

On 23/07/2020 16:28, Nicolai Hähnle via llvm-dev wrote:
> 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_.
> 
> It allows us to keep compiling against LLVM trunk in our CI, while one
> person goes and fixes up our use of the API (which we can detect
> automatically thanks to the warning or -Werror). It also makes it
> easier for us to bisect regressions across such API changes.
> 
> With the alternative, where 1-4 are all in a single commit, our
> integration with LLVM trunk is blocked until somebody can fix it --
> which is usually as quick as 1 or 2 days, but during that time window
> we don't catch any_other_  regressions in LLVM trunk that might affect
> us.
> 
> So please, let's make it a common rule to use this two-step,
> transactional approach to changes in APIs that are relatively
"core"
> (which mostly means llvm/IR, llvm/ADT, llvm/Support, perhaps with a
> side of llvm/Analysis). I am perfectly fine with this rule being
> broken occasionally, for changes where it would be exceedingly tricky
> to do them in a non-flag-day way. But in our experience, most of the
> changes that would actually affect an out-of-tree frontend aren't this
> tricky.
I agree that deprecation is much more friendly but the last time I 
proposed it there was a lot of push-back.  Given this thread is about 
documenting the existing policy, rather than changing the policy, I I'd 
recommend starting a new RFC thread about deprecation.

David

Hi Nicolai,

I think there are two distinct, somewhat loosely connected questions here:

1. Spelling out the (existing, implicit) policy explicitly in the documentation.
2. What the actual policy is and potentially changing it to make things easier
for downstream.

I started this thread with the intention of tackling 1 and not 2. I think the
conversation around 2 is much harder as it will require consensus-building
between a large number of people, especially given that what you are suggesting
seems to be somewhat of a departure from current practices. So I think it would
better to have a separate thread on changing the policy.

If there is agreement on changing the policy, we can certainly go back and
update the policy document to reflect the changes.

Varun
> On Jul 23, 2020, at 8:28 AM, Nicolai Hähnle <nhaehnle at gmail.com>
wrote:
> 
> Hi Varun,
> 
> On Wed, Jul 22, 2020 at 2:17 AM Varun Gandhi via llvm-dev
> <llvm-dev at lists.llvm.org <mailto: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_.
> 
> It allows us to keep compiling against LLVM trunk in our CI, while one
> person goes and fixes up our use of the API (which we can detect
> automatically thanks to the warning or -Werror). It also makes it
> easier for us to bisect regressions across such API changes.
> 
> With the alternative, where 1-4 are all in a single commit, our
> integration with LLVM trunk is blocked until somebody can fix it --
> which is usually as quick as 1 or 2 days, but during that time window
> we don't catch any _other_ regressions in LLVM trunk that might affect
> us.
> 
> So please, let's make it a common rule to use this two-step,
> transactional approach to changes in APIs that are relatively
"core"
> (which mostly means llvm/IR, llvm/ADT, llvm/Support, perhaps with a
> side of llvm/Analysis). I am perfectly fine with this rule being
> broken occasionally, for changes where it would be exceedingly tricky
> to do them in a non-flag-day way. But in our experience, most of the
> changes that would actually affect an out-of-tree frontend aren't this
> tricky.
> 
> Cheers,
> Nicolai
> 
> 
>> * Release stability: The C++ API does not make any stability guarantees
for the release branch.
>> * Testing: Patches to the C++ API are expected to come with tests just
like any other patch.
>> * Including new things into the API: [TODO: I'm not sure what
should go here].
>> * Documentation: Changes to the C++ API are not expected to be
documented in the release notes.
>> ---
>> 
>> Clang does have a page with information about its own C++ API
(https://clang.llvm.org/docs/Tooling.html) which is more informative, but I
think it would useful to have this information on the Developer Policy page for
the whole of LLVM.
>> 
>> Does this addition sound reasonable?
>> 
>> Varun
>> _______________________________________________
>> LLVM Developers mailing list
>> llvm-dev at lists.llvm.org <mailto:llvm-dev at lists.llvm.org>
>> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
<https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev>
> 
> 
> 
> -- 
> Lerne, wie die Welt wirklich ist,
> aber vergiss niemals, wie sie sein sollte.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200723/1e81f8a7/attachment.html>

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.

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".

So I am against any policy or encouragement to endorse this right now.

(I also agree with David that this would be a change in practice and as
such likely deserves its own RFC thread).

Best,

-- 
Mehdi


> It allows us to keep compiling against LLVM trunk in our CI, while one
> person goes and fixes up our use of the API (which we can detect
> automatically thanks to the warning or -Werror). It also makes it
> easier for us to bisect regressions across such API changes.
>
> With the alternative, where 1-4 are all in a single commit, our
> integration with LLVM trunk is blocked until somebody can fix it --
> which is usually as quick as 1 or 2 days, but during that time window
> we don't catch any _other_ regressions in LLVM trunk that might affect
> us.
>
> So please, let's make it a common rule to use this two-step,
> transactional approach to changes in APIs that are relatively
"core"
> (which mostly means llvm/IR, llvm/ADT, llvm/Support, perhaps with a
> side of llvm/Analysis). I am perfectly fine with this rule being
> broken occasionally, for changes where it would be exceedingly tricky
> to do them in a non-flag-day way. But in our experience, most of the
> changes that would actually affect an out-of-tree frontend aren't this
> tricky.
>
> Cheers,
> Nicolai
>
>
> > * Release stability: The C++ API does not make any stability
guarantees
> for the release branch.
> > * Testing: Patches to the C++ API are expected to come with tests just
> like any other patch.
> > * Including new things into the API: [TODO: I'm not sure what
should go
> here].
> > * Documentation: Changes to the C++ API are not expected to be
> documented in the release notes.
> > ---
> >
> > Clang does have a page with information about its own C++ API (
> https://clang.llvm.org/docs/Tooling.html) which is more informative, but
> I think it would useful to have this information on the Developer Policy
> page for the whole of LLVM.
> >
> > Does this addition sound reasonable?
> >
> > Varun
> > _______________________________________________
> > LLVM Developers mailing list
> > llvm-dev at lists.llvm.org
> > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
>
>
> --
> Lerne, wie die Welt wirklich ist,
> aber vergiss niemals, wie sie sein sollte.
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20200723/c0cf6d57/attachment.html>