In my recent tearful apology to the victims of the M5a build and their families, I made a reference to the Eclipse API prime directive that deserves further explanation. The accurate quote is:
API Usage Assumption: Every aspect of the API matters to some Client.
This quote comes from a seminal document written by Eclipse veteran Jim Des Rivieres who was in his time known as 'the API Police'. He struck fear in many a component lead when the time came to inspect the APIs before the freeze. Jim is now busy doing other interesting things (although he still lovingly prepares Eclipse New&Noteworthy for the milestone builds), but I encourage every committer to frequently come back to the said document, particularly when she prepares for the major API surgery (note from the revision history that the document has been kept fresh, most recently updated to include rules related to JDK 1.5).
Read the document and you will learn how to walk the razor-thin line between the API bliss and the M5a.