Juergen Schmidt wrote: > Mathias Bauer wrote: >> Frank Schönheit - Sun Microsystems Germany wrote: >> >>> Sorry, I stay with this: API should be as good as reasonably possible >>> *before* put into the MWS, or even a release. And this requires >>> discussion, most of the time. >> >> No objection. I just don't want to have any formal process. Announcing a >> change, taking part in discussions and reacting on reasonable requests >> should be enough. >> > > late but hopefully not too late ;-) > > I tend to agree to most of the points and let me summarize the points > that are important for me > > - changes of published APIs or changes in language binding are allowed > to major releases only > - keep it simple, no complicate processes > - discussion about API changes are a must > - one requirement -> migration guides. That means i would like to see a > small migration guide for all API changes. A special section in the API > area of the wiki where changes are documented and where API users can > easy see the old and new way to use the API. Especially external > developers, extension developers can look here to adapt there code easy. > This special migration section should be separated by releases. > It should be still naturally that all new APIs or changed APIs are > documented in the DevGuide wiki ;-) > > The DevGuide with related examples for beginners adn as consistent > developer docu, the migration page for experienced developers to help > them with changes. > > I really don't want to let our API users alone with potential changes. > And for that reason a migration guide is absolutely necessary. Trivial > changes should be only listed, more complex changed should be documented > in detail. Nobody will find it later in the mailing list archives.
Sounds like a plan. Let's move that forward! There's one thing that I would like to add, just a hint to everybody who wants to change APIs. The time between the branch-off of a code line for a release (formerly known as "code freeze") and the next one is roughly 6 months. This is the maximum time span for having the changes in the master before the code gets released, thus giving everybody time to test the change, adapt own code, perhaps asking for changes etc. The shortest time span is having the code integrated short before the branch-off of the beta version for the major release. It won't give much room for others to test the changes and get used to them. For non-trivial API changes I would like to recommend that the CWS containing them and of course all internal code changes (means: inside of OOo's code base) should be ready for integration as early as possible, just like we want it for a really huge feature. IMHO there shouldn't be any non-trivial API change that doesn't give "external" developers at least a month or so to adapt their code and come up with detected problems that might cause further changes. Let's make this a recommendation for all developers planing API changes and make them aware that API changes with a large influence may have to wait for another major release if they arrive very short before the beta of the upcoming release is branched off. We shouldn't set any fixed dates, but take that into consideration in the discussions of the proposed API changes. Regards, Mathias -- Mathias Bauer (mba) - Project Lead OpenOffice.org Writer OpenOffice.org Engineering at Sun: http://blogs.sun.com/GullFOSS Please don't reply to "[email protected]". I use it for the OOo lists and only rarely read other mails sent to it. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
