Once we finalize various interfaces, we need to slap our official stamp of approval on them so that users know they are something that won't change for future releases. We also need to fix the build process to export these headers to a new "blessed" sdk directory and add it to the CFLAGS as an include path. Subject: Re: API Review 6/1 Date: 2 Jun 2000 01:49:09 GMT From: email@example.com (Rick Gessner) Organization: Netscape Communications To: Warren Harris <firstname.lastname@example.org> CC: Brendan Eich <email@example.com>, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org Newsgroups: netscape.public.mozilla.porkjockeys References: 1 , 2 , 3 , 4 , 5 , 6 , 7 I'm in agreement with the stated goals; how about this compressed version: /** * @status: EXPERIMENTAL -- * @contact: email@example.com, or visit mozilla.org/api */ Warren Harris wrote: I think at the very least we have to state where to submit requests and comments, and dates for finalization. Saying what API something belongs to seems necessary too. Other pointers are helpful to people. You're not objecting to this are you? Warren Rick Gessner wrote: I'd prefer the terse form, with documentation on mozilla regarding the intrepretation. Rick Warren Harris wrote: I just think it's better if someone walking up to our codebase cold saw something like this: /** * @status EXPERIMENTAL * This is an experimental interface, used for the internal purposes in this * body of code. Developers should not base commercial products on this * interface as it may change at any time. Proposals to standardize this * interface may be submitted to firstname.lastname@example.org. USE AT YOUR OWN RISK! */ /** * @status UNDER_REVIEW * This interface is currently under review to become an officially supported part * of the mozilla platform. Submit comments and suggestions about this interface * on or before July 1, 2000 to email@example.com. After this time, this * interface will become frozen an can only be changed by introducing a new version * as described in http://www.mozilla.org/docs/interface-versioning.html. */ /** * @status FROZEN * @version 1.0 * This interface is frozen, and is an officially supported part of the Plugin API. * Developers may base commercial products on this interface. Bugs may be submitted * to http://bugzilla.mozilla.org under the Plugins component. This interface cannot * be changed except by the rules described in http://www.mozilla.org/docs/interface-versioning.html. */ Warren Brendan Eich wrote: Put it another way: if javadoc's @deprecated is sufficient, why is @status EXPERIMENTAL or @experimental not sufficient? /be Subject: Re: API Review 6/1 Date: 1 Jun 2000 19:16:05 GMT From: firstname.lastname@example.org (Brendan Eich) Organization: Another Netscape Collabra Server User To: Warren Harris <email@example.com> CC: Rick Gessner <firstname.lastname@example.org>, email@example.com, firstname.lastname@example.org, email@example.com Newsgroups: netscape.public.mozilla.porkjockeys References: 1 , 2 , 3 , 4 , 5 , 6 , 7 Warren Harris wrote: > I think at the very least we have to state where to submit requests > and comments, and dates for finalization. Saying what API something > belongs to seems necessary too. Other pointers are helpful to people. > You're not objecting to this are you? No one objects to those, but I think we should stick with javadoc precedent: @author, @see, possibly others. Javadoc experts, please chime in. /be
marking nsbeta3- as we won't hold pr3 for this.
This is completely harmless to the code, and would be a big help to developers attempting to figure out what they can depend on in the mozilla0.9 release.
Updating QA Contact
Let's stick w/ javadoc precedent for everything but @status. Rather than muddying the waters w/ a lot of prose, let's just use the javadoc monikers for indication. We can post to newsgroups and explain the meaning behind our tokens on a web page somewhere. Narrowing the focus a bit WRT this discussion. Let's do this... Interfaces we're talking about exposing (primarily listed on http://www.mozilla.org/projects/embedding/apiReviewNotes.html), should have a simple javadoc styme comment at the top of the idl file like so: /** * @status UNDER_REVIEW */ if the iface has been stamped as public, that javadoc would look like /** * @status FROZEN * @version 1.0 */ This way things are nice and lxr'able. Of course if existing interface top-level javadoc already exists in the idl, the above tokens should be integrated w/ them. If we want to add @author, et al, great, but we can do that at anytime. Over to Rick who's going to make the first cut at this.
convention is now in use. moving milestone to 0.9.1
Correction: Changing QA contact for the Embed API bugs to David Epstein.
Re-targeting for mozilla 1.0
Bugs targeted at mozilla1.0 without the mozilla1.0 keyword moved to mozilla1.0.1 (you can query for this string to delete spam or retrieve the list of bugs I've moved)
don't move bugs that are in the 1.0 dependency tree. sorry.
I'm not sure whether or not we want to close this bug out, or leave it in and make a final sweep for frozen APIs. I feel like we've got the convention in place, and individual bugs assigned to APIs we know we need to freeze, so, I'm going to snuff this.
"Under Review" & "Frozen" stamps are being applied to .idl files. The method appears to be working well.