API Freezing granularity
milestone customersThese customers are able to touch down on the Mozilla tree on a relatively frequent basis. They may integrate Mozilla into their trees hourly, daily, monthly, or on a formal Mozilla milestone release basis. They touch down on the Mozilla tree usually as frequently as they have the resources to do so. They often have a desire, rather than a requirement, for frozen interfaces.
snapshot customersThese customers are accustomed to shrink wrapped SDKs that provide the functionality they're interested in. This SDK package provides documentation (sometimes in the form of a published/bound/physical book), a frozen set of APIs that will be reliable and static, regardless of upgrades to the SDK, for the lifetime of the SDK, sometimes source code and debug libraries are made available and are of interest to snapshot customers.
They consider Mozilla a component in their software that is quite static. They want to minimize their resource expenditure (from cvs pull, to compiling/linking) during Mozilla integration. These customers require frozen APIs.
A general mapping of the two types of customers I outlined above, to frozen state, may look like:
Milestone customers - cvs pull granularity, Mozilla milestone granularity
Snapshot customers - Mozilla milestone granularity, API granularity
cvs pull granularity (fluid/liquid)
An API is frozen for the duration of a cvs pull of a source tree. If I never update my pull, the interfaces I'm using are effectivly frozen, regardless of whether or not they are actually changing on another branch/trunk. The next time I update my pull, I may be required to update any API integration points that have changed.
Mozilla milestone granularity (a higher level abstraction on top of the "cvs pull granularity") (steam/plasma)
Another level of freezing may be a Mozilla milestone. Perhaps I write my code based on a Mozilla 1.0 milestone cvs pull. I may be perfectly happy sticking with that Mozilla 1.0 milestone pull for the lifetime of my application/product. So, just like with "cvs pull granularity," I will only be required to update any API integration points that have changed the next time I update my Mozilla milestone pull.
API granularity (frozen/solid)
The frozen nature of an API crosses all source tree branches based off of the branch (or trunk) on which the API was frozen, and beyond. This level of granularity guarantees backwards compatibility (which insulates a consumer from updating their own integration points in their code). Currently, in the Mozilla source tree, an interface is considered "frozen" once the "@status FROZEN" text appears in the interface's .idl file .
many frozen APIs, and individuals focused on SDK related initiatives including Mozilla Runtime Environment versioning/sharing/distribution, modular/customizable cvs pulls/builds, formal SDK infrastructure, as well as embedding test harnesses on Linux, Windows and Mac.
The netscape.public.mozilla.embedding newsgroup provides discussion regarding which APIs are interesting to freeze, in the embedding browser context, and what would need to be done to freeze them. Generally these discussions are taken into real-time, public, API reviews.
An interface is considered frozen once the "@status FROZEN" text appears in the interface's .idl file . Here is an example of a frozen interface, nsIWebBrowser. Just like any other code change to Mozilla, API freezing requires a bug. Here's an example of an API freezing bug. Also, checkout the bottom of this doc for some assistance on how to actually mark an interface as frozen.
A FROZEN interface can never change. It is a contract between the caller and the callee that is frozen in time which provides backwards compatibility. See this doc to determine how to "rev" a frozen interface.
API reviews are generally suggested and announced on the netscape.public.mozilla.embedding.