Closed Bug 48726 Opened 20 years ago Closed 18 years ago

slap stamp of approval on "blessed" headers

Categories

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

defect

Tracking

(Not tracked)

VERIFIED FIXED
mozilla1.0

People

(Reporter: warrensomebody, Assigned: rpotts)

References

Details

(Keywords: arch, embed, topembed, Whiteboard: [nsbeta3-])

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: 
               rickg@netscape.com (Rick Gessner)
 Organization: 
               Netscape Communications
           To: 
               Warren Harris <warren@netscape.com>
          CC: 
               Brendan Eich <brendan@meer.net>, vidur@netscape.com, 
porkjockeys@mozilla.org,
               mozilla@elemental.com
  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: porkjockeys@mozilla.org, 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 porkjockeys@mozilla.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 porkjockeys@mozilla.org. 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: 
               brendan@meer.net (Brendan Eich)
 Organization: 
               Another Netscape Collabra Server User
           To: 
               Warren Harris <warren@netscape.com>
          CC: 
               Rick Gessner <rickg@netscape.com>, vidur@netscape.com, 
porkjockeys@mozilla.org,
               mozilla@elemental.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
Keywords: nsbeta3
Keywords: arch
Whiteboard: [nsbeta3+]
Target Milestone: --- → M18
Priority: P3 → P1
marking nsbeta3- as we won't hold pr3 for this.
Whiteboard: [nsbeta3+] → [nsbeta3-]
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.
Keywords: embed
Target Milestone: M18 → mozilla0.9
Updating QA Contact
QA Contact: jrgm → mdunn
Blocks: 70229
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.
Assignee: valeski → rpotts
convention is now in use. moving milestone to 0.9.1
Target Milestone: mozilla0.9 → mozilla0.9.1
Correction: Changing QA contact for the Embed API bugs to David Epstein.
QA Contact: mdunn → depstein
Target Milestone: mozilla0.9.1 → mozilla0.9.2
Re-targeting for mozilla 1.0
Target Milestone: mozilla0.9.2 → mozilla1.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)
Target Milestone: mozilla1.0 → mozilla1.0.1
don't move bugs that are in the 1.0 dependency tree. sorry.

Target Milestone: mozilla1.0.1 → mozilla1.0
Keywords: topembed
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.
Status: NEW → RESOLVED
Closed: 18 years ago
Resolution: --- → FIXED
"Under Review" & "Frozen" stamps are being applied to .idl files. The method
appears to be working well.
Status: RESOLVED → VERIFIED
Product: Core → Core Graveyard
You need to log in before you can comment on or make changes to this bug.