slap stamp of approval on "blessed" headers

VERIFIED FIXED in mozilla1.0

Status

()

Core
Embedding: APIs
P1
normal
VERIFIED FIXED
17 years ago
16 years ago

People

(Reporter: Warren Harris, Assigned: rpotts (gone))

Tracking

({arch, embed, topembed})

Trunk
mozilla1.0
arch, embed, topembed
Points:
---

Firefox Tracking Flags

(Not tracked)

Details

(Whiteboard: [nsbeta3-])

(Reporter)

Description

17 years ago
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
(Reporter)

Updated

17 years ago
Keywords: nsbeta3

Updated

17 years ago
Keywords: arch
Whiteboard: [nsbeta3+]

Updated

17 years ago
Target Milestone: --- → M18

Updated

17 years ago
Priority: P3 → P1

Comment 1

17 years ago
marking nsbeta3- as we won't hold pr3 for this.
Whiteboard: [nsbeta3+] → [nsbeta3-]
(Reporter)

Comment 2

17 years ago
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.

Updated

17 years ago
Keywords: embed

Updated

17 years ago
Target Milestone: M18 → mozilla0.9

Comment 3

17 years ago
Updating QA Contact
QA Contact: jrgm → mdunn

Updated

17 years ago
Blocks: 70229

Comment 4

17 years ago
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

Comment 5

17 years ago
convention is now in use. moving milestone to 0.9.1
Target Milestone: mozilla0.9 → mozilla0.9.1

Comment 6

17 years ago
Correction: Changing QA contact for the Embed API bugs to David Epstein.
QA Contact: mdunn → depstein
(Assignee)

Updated

17 years ago
Target Milestone: mozilla0.9.1 → mozilla0.9.2
Re-targeting for mozilla 1.0
Target Milestone: mozilla0.9.2 → mozilla1.0

Comment 8

16 years ago
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

Comment 9

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

Target Milestone: mozilla1.0.1 → mozilla1.0

Updated

16 years ago
Keywords: topembed

Comment 10

16 years ago
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
Last Resolved: 16 years ago
Resolution: --- → FIXED

Comment 11

16 years ago
"Under Review" & "Frozen" stamps are being applied to .idl files. The method
appears to be working well.
Status: RESOLVED → VERIFIED
You need to log in before you can comment on or make changes to this bug.