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

[Nicolai Hähnle via llvm-dev]

On Thu, Jul 23, 2020 at 6:18 PM Varun Gandhi <varun_gandhi at apple.com> wrote:
> 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.

The existing, implicit policy is non-existent though. Folks have been
using the deprecation approach that I described in my earlier email
already, it just hasn't been applied consistently.

So to pretend that the existing policy is that there is no attention
paid to deprecation would not be correct. If the goal is to restrict
this discussion to your point 1, that's fair, but then you do need to
mention that care for deprecation is sometimes being done, just not
consistently. I'd be happy to start a separate thread afterwards to
suggest amending that to making it tighter.

Cheers,
Nicolai



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


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