Contents
Customer DefinitionsAPI Freezing granularity
Freezing process
API Reviews
Appendix
Customer Definitions
The Mozilla tree is a resource for many customers who use its products in a variety of ways. Some customers use the standalone Mozilla browser provided in pre-built form with a installer while others integrate Mozilla as an embeddable browser into their application. The latter customer has in interest in API stability and backwards compatibility and can be generally categorized into the following...milestone customers
These 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 customers
These 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
API Freezing granularity
There are different levels of "frozen" APIs. An analogy could be the three (generaly accepted) high level states of matter: fluid/liquid, steam/plasma, frozen/solid.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 [1].
Freezing process
In order for Mozilla to meet the needs of these two categories of customers, more energy and focus needs to be expended on the snapshot customers. Mozilla is a haven for milestone customers, however, has a lot of work to do for snapshot customers. In an effort to meet their needs, various Mozilla contributors (including Netscape) mobilized a couple of years ago to start providing API granularity freezing. Today Mozilla has 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 [1]. 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
API reviews provide a forum for interested parties to discuss the freezing of interfaces. Anyone can establish an API review discussion, and it is strongly advisable to make such discussions public. API reviews that Netscape has sponsored have their notes published here.API reviews are generally suggested and announced on the netscape.public.mozilla.embedding.