[LLVMdev] Question about changes to llvm::Argument::addAttr(AttributeSet AS) API

[Bill Wendling]

On Feb 6, 2013, at 2:31 AM, David Chisnall <David.Chisnall at cl.cam.ac.uk> wrote:

> On 6 Feb 2013, at 07:50, Bill Wendling wrote:
> 
>> On Feb 4, 2013, at 11:54 PM, David Chisnall <David.Chisnall at cl.cam.ac.uk> wrote:
>> 
>>> On 5 Feb 2013, at 01:32, Bill Wendling wrote:
>>> 
>>>> No. It hasn't been written up. We typically don't do write-ups for API changes. However, we do list the thing we do change in the ReleaseNotes (these changes haven't made it there though).
>>> 
>>> The attributes API has undergone a horrendous amount of churn over the last few months, both before and after the 3.2 release.  I've lost track of the number of times I've rewritten code interacting with this API over the past year and I now have a mess of #ifdefs just to support 3.1, 3.2 and trunk.  Each time, the only warning I got was that my code stopped building with trunk, and the only way of knowing how to rewrite it was to read the attributes code.
>>> 
>> I'm sorry about the problems. It's a continuing problem when working with a project where the APIs are not set in stone and are subject to change at a moment's notice.
> 
> APIs in LLVM are not set in stone because we want to be able to evolve them as the requirements change.  That should not be a license to constantly rewrite APIs with large numbers of consumers, but simply an indication that if the choice is between fixing the code and maintaining backwards compatibility then developers are free to fix the code.  That doesn't mean that we should never think about the cost to downstream developers when we churn APIs, it just means that we shouldn't be held in a straitjacket by these concerns.  
> 
> And the cost of changing an API is that it MUST be properly documented.  Whenever you make the choice to break an API, you are saying 'I am saving my time by not writing compatibility interfaces, and everyone else must rewrite their code to support my changes.'  If you then compound this by saying 'oh, and if you want to know how to rewrite your code, then read my code, my time is too valuable to waste documenting my work' then you do not encourage people to depend on LLVM.
> 
You don't understand what I'm saying. The APIs were changing way too quickly for it to make sense to create such a document. I tried as best as I could to mitigate all of the problems, but there were several intermediate steps that had to happen before the attributes classes were in a proper state for the new feature work. The typical way to understand the APIs is to read the header files and/or look at existing code. The changes I made showed how to use the new APIs while I was going along.

>>> It would be really great if whoever is responsible could step back from their code editor for a few minutes and write some documentation on how to migrate from each iteration to the next.
>>> 
>> That would be more trouble than it's worth because the API is changing quite rapidly right now. A lot of it hasn't solidified just yet. Basically, once a migration doc was written it would be immediately out of date.
> 
> This comment is indicative of a code first, think second mentality.  If the APIs are changing so quickly that even a high-level overview and broad migration guide would be out of date before it's finished then it seems pretty clear that the design stage was skipped entirely.

Not so. I had to change the existing attributes classes so that they a) still worked while I changed them, and b) would be in a state afterwards where they would support the new features we needed. The intermediate steps that were taken were necessary. They would have happened if I used git or cvs or any other vcs.

> While this is fine for code on the edges (e.g. a back-end under development, where changes don't affect any other users), it generates a lot of problems of people when it is code that is central to LLVM.  
> 
> Effectively, here, you are saying that your time is far more valuable than everyone else's.

Wrong. I'm saying that the document would be a waste of electrons because it would be out of date with the next change.

> You can, I hope, understand why this is not an opinion shared by those whose time you are spending to save some of your own.  When you save 10 minutes of your time by not writing docs, you then make every user of this API (which means the author every out-of-tree front end, a lot of out-of-tree passes, and some back ends) spend at least twice that time each reading the code to try to figure out what the new equivalent of the old API is.  
> 
Each step along the way had changes to existing API uses in the code base. If you wanted examples, those were them.