Owen Anderson wrote:> On Jul 15, 2009, at 7:44 AM, John Criswell wrote: > >> 1) If technically possible, add the new API first, get it working, >> email >> llvmdev describing the old and new APIs, provide some lead time for >> people to change over, and then remove the old APIs. This makes it >> easier to plan when I fix problems due to LLVM API changes and when I >> can work on our own bugs. :) >> > > The high-level change was already described and discussed on LLVMdev. >First, did you discuss it or announce it? There's a difference. With its high traffic volume, I don't read all llvmdev mails anymore. I pick and choose based on their subject lines. A subject entitled "API Change: LLVMContext" will probably get my attention while "Multi-threading support for LLVM" will not. Second, the only emails I remember on the topic was an email that provided a short description of LLVMContext and some followup emails on questions/commit messages from me. The first message announcing LLVMContext was too vague; it required that the reader think about the LLVM implementation and logically deduce what was going to change. The text you've written below is much more clear: you say methods x, y, and z are moving from class a to b. That information and doxygen is usually all I need. What I'm suggesting is that you should announce a change in a way that makes it easy for LLVM users to understand what they need to do to understand their code. The announcement can't assume that the reader knows about LLVM internals (like how uniquing is implemented), and it can't be part of some larger discussion on how the change should be made. What you've written below is perfect; I think it would have been better if you had sent it earlier. Perhaps you did, and I missed it, or perhaps I'm being too picky. In that case, I apologize. I think I've said enough on the matter. My points are meant as constructive criticism; use them in whatever way you feel is best. -- John T.> The summary is that the static factory methods on Constant and Type > are going away, and becoming instance methods on LLVMContext. All of > the instance methods are already in place (though many just forward to > the static implementations for the moment). I'm currently in the > process of moving the implementations over, removing the static > versions, and updating the LLVM tree for it. > > For basic constant-fetching API changes, which make up the bulk of the > changes, the update should be trivial: switching to the corresponding > instance method on LLVMContext. In general, I've tried to make the > mapping of static function names to instance method names obvious, so > it should be straightforward. > > Slightly more tricky are the API changes made incidentally to moving > to LLVMContext, like the GlobalValue constructor change. These > occurred because it was necessary to pass a context in where it wasn't > available before. I'll try to provide more notice about these, but, > again, they should be relatively limited in scope. > > --Owen
On Jul 15, 2009, at 9:53 AM, John Criswell wrote:> Owen Anderson wrote: >> On Jul 15, 2009, at 7:44 AM, John Criswell wrote: >> >>> 1) If technically possible, add the new API first, get it working, >>> email >>> llvmdev describing the old and new APIs, provide some lead time for >>> people to change over, and then remove the old APIs. This makes it >>> easier to plan when I fix problems due to LLVM API changes and >>> when I >>> can work on our own bugs. :) >>> >> >> The high-level change was already described and discussed on LLVMdev. >> > First, did you discuss it or announce it? There's a difference. > > With its high traffic volume, I don't read all llvmdev mails > anymore. I > pick and choose based on their subject lines. A subject entitled "API > Change: LLVMContext" will probably get my attention while > "Multi-threading support for LLVM" will not.How about a subject line "[LLVMdev] MAJOR API CHANGE: LLVMContext"? --Owen -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20090715/7a5de096/attachment.html>
Jean-Daniel Dupas
2009-Jul-15 17:56 UTC
[LLVMdev] LLVMContext: Suggestions for API Changes
Le 15 juil. 09 à 19:07, Owen Anderson a écrit :> > On Jul 15, 2009, at 9:53 AM, John Criswell wrote: > >> Owen Anderson wrote: >>> On Jul 15, 2009, at 7:44 AM, John Criswell wrote: >>> >>>> 1) If technically possible, add the new API first, get it working, >>>> email >>>> llvmdev describing the old and new APIs, provide some lead time for >>>> people to change over, and then remove the old APIs. This makes it >>>> easier to plan when I fix problems due to LLVM API changes and >>>> when I >>>> can work on our own bugs. :) >>>> >>> >>> The high-level change was already described and discussed on >>> LLVMdev. >>> >> First, did you discuss it or announce it? There's a difference. >> >> With its high traffic volume, I don't read all llvmdev mails >> anymore. I >> pick and choose based on their subject lines. A subject entitled >> "API >> Change: LLVMContext" will probably get my attention while >> "Multi-threading support for LLVM" will not. > > How about a subject line "[LLVMdev] MAJOR API CHANGE: LLVMContext"?You mean like this subject ? http://lists.cs.uiuc.edu/pipermail/llvmdev/2009-June/023505.html -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20090715/a6884799/attachment.html>
Owen Anderson wrote:> > On Jul 15, 2009, at 9:53 AM, John Criswell wrote: > >> Owen Anderson wrote: >>> On Jul 15, 2009, at 7:44 AM, John Criswell wrote: >>> >>>> 1) If technically possible, add the new API first, get it working, >>>> email >>>> llvmdev describing the old and new APIs, provide some lead time for >>>> people to change over, and then remove the old APIs. This makes it >>>> easier to plan when I fix problems due to LLVM API changes and when I >>>> can work on our own bugs. :) >>>> >>> >>> The high-level change was already described and discussed on LLVMdev. >>> >> First, did you discuss it or announce it? There's a difference. >> >> With its high traffic volume, I don't read all llvmdev mails anymore. I >> pick and choose based on their subject lines. A subject entitled "API >> Change: LLVMContext" will probably get my attention while >> "Multi-threading support for LLVM" will not. > > How about a subject line "[LLVMdev] MAJOR API CHANGE: LLVMContext"?Yes, that particular message fits the first criterion: it announces the change in the subject line. I thought you might have been referring to other emails about LLVMContext that I didn't see, but you weren't; you were referring to the above message. However, IMHO, the message from June doesn't clearly state what is to change. It tells me static methods will be removed, but it doesn't tell me where they are re-implemented. It assumes I can infer that by understanding how LLVM uniques values. -- John T.> > --Owen