48726 - slap stamp of approval on "blessed" headers

Status: VERIFIED FIXED

(Core Graveyard :: Embedding: APIs, defect, P1)

Description

[Warren Harris]

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: 
               [e-mail] (Rick Gessner)
 Organization: 
               Netscape Communications
           To: 
               Warren Harris <[e-mail]>
          CC: 
               Brendan Eich <[e-mail]>, [e-mail], 
[e-mail],
               [e-mail]
  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: [e-mail], 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 [e-mail]. 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 [e-mail]. 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: 
               [e-mail] (Brendan Eich)
 Organization: 
               Another Netscape Collabra Server User
           To: 
               Warren Harris <[e-mail]>
          CC: 
               Rick Gessner <[e-mail]>, [e-mail], 
[e-mail],
               [e-mail]
  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

Comment 1

[Michael La Guardia]

marking nsbeta3- as we won't hold pr3 for this.

Comment 2

[Warren Harris]

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.

Comment 3

[Paul Wyskoczka]

Updating QA Contact

Comment 4

[Judson Valeski]

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.

Comment 5

[Judson Valeski]

convention is now in use. moving milestone to 0.9.1

Comment 6

[Michael Dunn]

Correction: Changing QA contact for the Embed API bugs to David Epstein.

Comment 7

[Radha on family leave (not reading bugmail)]

Re-targeting for mozilla 1.0

Comment 8

[Asa Dotzler [:asa]]

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)

Comment 9

[Asa Dotzler [:asa]]

don't move bugs that are in the 1.0 dependency tree. sorry.

Comment 10

[Judson Valeski]

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.

Comment 11

[David Epstein]

"Under Review" & "Frozen" stamps are being applied to .idl files. The method
appears to be working well.