Hi Juergen, Sean, I definitely agree with needing to write down the policy and definitely any policy should include a deprecation time :) Did you want to write up something and let us poke at it? A couple of thoughts outside of a deprecation policy: a) guarantee that the api itself won't go away, but could possibly be turned into a noop? (i.e. source compatibility) b) versioning? (Should we add support for versioning in anyhow? Maybe a C API version 2 to start this off with?) c) One of the big things appears to be the push and pull for "A C API for all C++ entry points" along with "We don't want to get locked into immobility because we have a C API for all C++ entry points". Perhaps part of this might be defining an actual stable set of things along with an unstable set of things? What was the rest of your discussion on this? Any particular points you think the community would be interested in? Just some random thoughts. -eric On Fri, Jul 17, 2015 at 12:54 PM Sean Silva <chisophugis at gmail.com> wrote:> I think it makes sense to officially document this. It has apparently > never graduated from being "tribal knowledge". > > As far as the concrete details, I haven't thought too much, but the > deprecation process you suggested makes sense to me. > > -- Sean Silva > > On Fri, Jul 17, 2015 at 12:36 PM, Juergen Ributzka <juergen at apple.com> > wrote: > >> Hi @ll, >> >> a few of us had recently a discussion about how to manage the C API and >> possible policies regarding addition, maintenance, deprecation, and removal >> of API. >> >> Even thought there is a strong agreement in the community that we >> shouldn't break released C API and should be backwards compatible, there >> doesn’t seem to be a developer policy that backs that up. This is something >> we should fix. >> >> I was wondering what the interested parties think of the current approach >> and what could/should we improve to make the use and maintenance of the C >> API easier for users and the developers alike. >> >> I was hoping we could also introduce a process that allows the removal of >> an API after it has been deprecated for a whole release and the release >> notes stated that it will be removed. >> >> Thoughts? Comments? >> >> Cheers, >> Juergen >> _______________________________________________ >> LLVM Developers mailing list >> LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu >> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >> > >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150717/fffd11b8/attachment.html>
Oh, one other addition here: I'm totally ok with a small first patch that puts in a developer policy of "we try to keep the C API stable across releases and the deprecation policy is blah blah blah" -eric On Fri, Jul 17, 2015 at 1:21 PM Eric Christopher <echristo at gmail.com> wrote:> Hi Juergen, Sean, > > I definitely agree with needing to write down the policy and definitely > any policy should include a deprecation time :) > > Did you want to write up something and let us poke at it? > > A couple of thoughts outside of a deprecation policy: > > a) guarantee that the api itself won't go away, but could possibly be > turned into a noop? (i.e. source compatibility) > b) versioning? (Should we add support for versioning in anyhow? Maybe a C > API version 2 to start this off with?) > c) One of the big things appears to be the push and pull for "A C API for > all C++ entry points" along with "We don't want to get locked into > immobility because we have a C API for all C++ entry points". Perhaps part > of this might be defining an actual stable set of things along with an > unstable set of things? > > What was the rest of your discussion on this? Any particular points you > think the community would be interested in? > > Just some random thoughts. > > -eric > > On Fri, Jul 17, 2015 at 12:54 PM Sean Silva <chisophugis at gmail.com> wrote: > >> I think it makes sense to officially document this. It has apparently >> never graduated from being "tribal knowledge". >> >> As far as the concrete details, I haven't thought too much, but the >> deprecation process you suggested makes sense to me. >> >> -- Sean Silva >> >> On Fri, Jul 17, 2015 at 12:36 PM, Juergen Ributzka <juergen at apple.com> >> wrote: >> >>> Hi @ll, >>> >>> a few of us had recently a discussion about how to manage the C API and >>> possible policies regarding addition, maintenance, deprecation, and removal >>> of API. >>> >>> Even thought there is a strong agreement in the community that we >>> shouldn't break released C API and should be backwards compatible, there >>> doesn’t seem to be a developer policy that backs that up. This is something >>> we should fix. >>> >>> I was wondering what the interested parties think of the current >>> approach and what could/should we improve to make the use and maintenance >>> of the C API easier for users and the developers alike. >>> >>> I was hoping we could also introduce a process that allows the removal >>> of an API after it has been deprecated for a whole release and the release >>> notes stated that it will be removed. >>> >>> Thoughts? Comments? >>> >>> Cheers, >>> Juergen >>> _______________________________________________ >>> LLVM Developers mailing list >>> LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu >>> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >>> >> >>-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150717/113acf66/attachment.html>
> c) One of the big things appears to be the push and pull for "A C API for > all C++ entry points" along with "We don't want to get locked into > immobility because we have a C API for all C++ entry points". Perhaps part > of this might be defining an actual stable set of things along with an > unstable set of things?This is a good idea. We should clearly document a subset that is stable. Being stable should also have a very high bar. Things like "we have a shipping product that has to work with two versions of llvm and has to dynamic link with it". So something that the webkit jit needs is in. Some API that is in C just so someone can statically link a C/Go/Ocaml program with llvm is not. Cheers, Rafael
On Fri, Jul 17, 2015 at 2:05 PM Rafael Espíndola <rafael.espindola at gmail.com> wrote:> > c) One of the big things appears to be the push and pull for "A C API for > > all C++ entry points" along with "We don't want to get locked into > > immobility because we have a C API for all C++ entry points". Perhaps > part > > of this might be defining an actual stable set of things along with an > > unstable set of things? > > This is a good idea. We should clearly document a subset that is stable. > > Being stable should also have a very high bar. Things like "we have a > shipping product that has to work with two versions of llvm and has to > dynamic link with it". > > So something that the webkit jit needs is in. Some API that is in C > just so someone can statically link a C/Go/Ocaml program with llvm is > not. > >This is pretty open to abuse, let's just define what seems to make sense rather than tying it like this. -eric> Cheers, > Rafael >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150717/642a8cde/attachment.html>
On 07/17/2015 02:05 PM, Rafael Espíndola wrote:>> c) One of the big things appears to be the push and pull for "A C API for >> all C++ entry points" along with "We don't want to get locked into >> immobility because we have a C API for all C++ entry points". Perhaps part >> of this might be defining an actual stable set of things along with an >> unstable set of things? > This is a good idea. We should clearly document a subset that is stable. > > Being stable should also have a very high bar. Things like "we have a > shipping product that has to work with two versions of llvm and has to > dynamic link with it".+1 to the general notion of stable vs unstable> > So something that the webkit jit needs is in. Some API that is in C > just so someone can statically link a C/Go/Ocaml program with llvm is > not.-1 to this particular definition thereof> > Cheers, > Rafael > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
On Sat, 18 Jul 2015 at 04:34 Eric Christopher <echristo at gmail.com> wrote:> Hi Juergen, Sean, > > I definitely agree with needing to write down the policy and definitely > any policy should include a deprecation time :) > > Did you want to write up something and let us poke at it? > > A couple of thoughts outside of a deprecation policy: > > a) guarantee that the api itself won't go away, but could possibly be > turned into a noop? (i.e. source compatibility) >This was done recently with the Go bindings to make the LLVM tree green, which led to not-immediately-obvious breakage in llgo. If source compatibility were broken, it would have been clear what needed to be changed. As a user, I'd prefer that over preserving source compatibility. b) versioning? (Should we add support for versioning in anyhow? Maybe a C> API version 2 to start this off with?) >c) One of the big things appears to be the push and pull for "A C API for> all C++ entry points" along with "We don't want to get locked into > immobility because we have a C API for all C++ entry points". Perhaps part > of this might be defining an actual stable set of things along with an > unstable set of things? >IMO, just having a single stable C API for the core would keep things clear; no having to check whether this function or that function is stable. Separate non-stable APIs can be maintained outside the core easily enough. They don't even need to be in-tree if they're not stable. What was the rest of your discussion on this? Any particular points you> think the community would be interested in? > > Just some random thoughts. > > -eric > > On Fri, Jul 17, 2015 at 12:54 PM Sean Silva <chisophugis at gmail.com> wrote: > >> I think it makes sense to officially document this. It has apparently >> never graduated from being "tribal knowledge". >> >> As far as the concrete details, I haven't thought too much, but the >> deprecation process you suggested makes sense to me. >> >> -- Sean Silva >> >> On Fri, Jul 17, 2015 at 12:36 PM, Juergen Ributzka <juergen at apple.com> >> wrote: >> >>> Hi @ll, >>> >>> a few of us had recently a discussion about how to manage the C API and >>> possible policies regarding addition, maintenance, deprecation, and removal >>> of API. >>> >>> Even thought there is a strong agreement in the community that we >>> shouldn't break released C API and should be backwards compatible, there >>> doesn’t seem to be a developer policy that backs that up. This is something >>> we should fix. >>> >>> I was wondering what the interested parties think of the current >>> approach and what could/should we improve to make the use and maintenance >>> of the C API easier for users and the developers alike. >>> >>> I was hoping we could also introduce a process that allows the removal >>> of an API after it has been deprecated for a whole release and the release >>> notes stated that it will be removed. >>> >>> Thoughts? Comments? >>> >>> Cheers, >>> Juergen >>> _______________________________________________ >>> LLVM Developers mailing list >>> LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu >>> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >>> >> >> _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150718/b0946db9/attachment.html>