Hi all,
I know this issue has been discussed over and over again, but I’d like to voice my opinion while 3.0 is still fairly early-ish in the pipeline.
So the issue is… API breakage. I understand and agree with the rationale why, namely faster development. But this principle should mean that for each breakage, the dude who makes the breakage should accompany the final commit (or something like that) with a detailed explanation about how to migrate existing codebases, relative to the previous LLVM release.
Fact is, the release document that explains the changes is not very useful for figuring out how to upgrade between releases.
I literally have to wade through tons of commits and mailing list postings for each release. I gave up on that a while ago and therefore use the outdated (and not bugfree) 2.5 release (!)
I’m a front end developer and only have time for the front end and a tiny bit of back end probing. With lacking release docs and no stable dot release scheme, things are getting rather frustrating. I’m thinkering about using the more stable C wrapper, but that’s pretty lame given the fact that my compiler is written in C++.
I don’t really buy the manpower argument. Updating the release doc when breaking the frigging API is the Right Thing To Do and shouldn’t take that long, when done when the change is fresh in memory.
This is my only gripe with llvm, but it’s a pretty big one. The lack of stable releases is a slightly lesser one, but in that case, I totally buy the manpower argument.
Thanks for listening.
I regularly make small API-breaking changes in the name of cleaning
things up. Sorry! I'd be happy to update the release notes if folks
reckon this is the right thing to do. Would it just mean adding a <ul>
to the (currently empty) list in docs/ReleaseNotes.html#api_changes ?
Jay.
I would like to second the request, I got tripped up when migrating
from 2.8 to 2.9 w.r.t. many of the changes in pass
initialization/registration.
Sure, that makes perfect sense.
-Chris
From: llvmdev-bounces@cs.uiuc.edu [mailto:llvmdev-bounces@cs.uiuc.edu]
On Behalf Of Chris Lattner
Sent: Wednesday, July 13, 2011 10:16 AM
To: Jay Foad
Cc: llvmdev@cs.uiuc.edu
Subject: Re: [LLVMdev] [Frustration] API breakage
>> I don't really buy the manpower argument. Updating the release doc
when
>> breaking the frigging API is the Right Thing To Do and shouldn't
take that
>> long, when done when the change is fresh in memory.
>
> I regularly make small API-breaking changes in the name of cleaning
> things up. Sorry! I'd be happy to update the release notes if folks
> reckon this is the right thing to do. Would it just mean adding a
<ul>
> to the (currently empty) list in docs/ReleaseNotes.html#api_changes ?
Sure, that makes perfect sense.
-Chris
[Villmow, Micah] If possible to add my own two cents. I would recommend
to add not just api changes, but default setting changes. Took us awhile
to figure out that with 2.9, NoAA was set to default instead of what was
in 2.8 and it caused some performance regressions on our side.
That's definitely needed. Not every LLVM user tracks development on trunk very closely and reads every commit message. A quick note about the nature of API-breaking changes and a hint on how to migrate existing sources would be really appreciated.
Albert
I second that.
Preferably all in the same place, in order, with (approx.) revision
numbers where it happened. It'd make our jobs much easier to merge our
local base with trunk.
A simple text would suffice:
<li><b>New Type System</b>: As of r123456, the type system is... Uses
of ... have been replaced by ..., ... and ... have been deprecated,
please use ... instead.</li>
cheers,
--renato
I've updated the release notes for all API changes I've made since 2.9
was branched:
http://lists.cs.uiuc.edu/pipermail/llvm-commits/Week-of-Mon-20110711/123990.html
Preferably all in the same place, in order, with (approx.) revision
numbers where it happened. It'd make our jobs much easier to merge our
local base with trunk.
I haven't gone into quite that much detail, sorry. I think adding svn
revision numbers will make the document unwieldy.
Jay.
That's fine. Those who follow the trunk closely should also follow the
commits closely. 
This doc is more important for releases anyway.
cheers,
--renato
Thanks. But what about the API changes related to the new type system (OpaqueType gone, etc.)? Is that documented somewhere? Shouldn't it be in the release notes as well? I'd really appreciate some hints on how to migrate sources to accommodate these changes.
Albert
Albert Graef <Dr.Graef@t-online.de> writes:
Yes, I'm planning to write a blog post about it and link it from the release notes.
-Chris