Closed
Bug 811960
Opened 13 years ago
Closed 13 years ago
Fix module metadata
Categories
(Add-on SDK Graveyard :: General, defect, P2)
Add-on SDK Graveyard
General
Tracking
(Not tracked)
RESOLVED
FIXED
People
(Reporter: wbamberg, Unassigned)
References
Details
Attachments
(2 files)
I'm updating the doc generation code to expose the stability index written into module metadata (bug 786286) and found some problems:
* these modules don't contain any metadata:
self
content/content-proxy
net/url
test/harness
test/runner
util/list
* we sort of agreed (I thought: https://blog.mozilla.org/addons/2012/10/01/a-lifecycle-for-the-add-on-sdks-apis/) that we'd not use "unstable", (using only "experimental", "stable", and "deprecated") but many modules use it. I think these should be changed to "experimental".
* "sdk/timers" is deprecated. Is that correct?
To help maintain this data, we should have a test that checks that each module contains a valid value for "stability".
Priority: -- → P2
Comment 1•13 years ago
|
||
`content/content-proxy` is not a module, so can't have metadata. Also, as soon as SDK doesn't have to support version < 17.0a2, we can remove it.
About the others, I would suggest to ask to Irakli (going to add him as target for "needinfo").
Flags: needinfo?(rFobic)
Comment 2•13 years ago
|
||
`content/content-proxy` is not a module, so can't have metadata. Also, as soon as SDK doesn't have to support version < 17.0a2, we can remove it.
About the others, I would suggest to ask to Irakli (going to add him as target for "needinfo").
Updated•13 years ago
|
Attachment #683699 -
Flags: review?(wbamberg)
Comment 4•13 years ago
|
||
This pull request adds metadata to a missing modules.
Zer0 is right about content/content-proxy it's not a module.
>
> * we sort of agreed (I thought: https://blog.mozilla.org/addons/2012/10/01/a-
> lifecycle-for-the-add-on-sdks-apis/) that we'd not use "unstable", (using only
> "experimental", "stable", and "deprecated") but many modules use it. I think
> these should be changed to "experimental".
>
I don't recall that to be honest & I believe modules end up with metadata that we
end up putting into spreadsheet. I can be convinced that we should change to
experimental if there were any reason for that.
> * "sdk/timers" is deprecated. Is that correct?
Nope, timer supposed to have deprecated and timers had to have stable. I guess there was a mixup. Fix is in pull request.
> To help maintain this data, we should have a test that checks that each module
> contains a valid value for "stability".
Yeap that's a good idea!
| Reporter | ||
Comment 5•13 years ago
|
||
(In reply to Irakli Gozilalishvili [:irakli] [:gozala] [@gozala] from comment #4)
> This pull request adds metadata to a missing modules.
>
> Zer0 is right about content/content-proxy it's not a module.
>
> >
> > * we sort of agreed (I thought: https://blog.mozilla.org/addons/2012/10/01/a-
> > lifecycle-for-the-add-on-sdks-apis/) that we'd not use "unstable", (using only
> > "experimental", "stable", and "deprecated") but many modules use it. I think
> > these should be changed to "experimental".
> >
>
> I don't recall that to be honest & I believe modules end up with metadata
> that we
> end up putting into spreadsheet. I can be convinced that we should change to
> experimental if there were any reason for that.
After we made the spreadsheet, I wrote up the API lifecycle in a blog post: https://blog.mozilla.org/addons/2012/10/01/a-lifecycle-for-the-add-on-sdks-apis/ and while doing that I thought just three categories would be sufficient, I emailed you, Jeff, and Mossop about it. Although I only got a positive answer from Mossop, I got no dissent from anyone else.
The reason is simple: there's no distinction we can make between "unstable" and "experimental" that's actually useful to developers. We basically define the categories like:
"experimental": can change without going through deprecation
"stable": can only change if we go through deprecation
"deprecated": will be removed/changed shortly, do not rely on it
For each category, the contract with developers is clearly defined. Where does "unstable" fit in? If it can change without going through deprecation, how is this really different to "experimental"? Is it somehow "more stable"? But what does that even mean, what does it usefully communicate to developers? What's the specific payload of "more stable", if it's not getting the deprecation treatment that actually stable modules get?
To be clear, I don't really mind if we have unstable. But I wasn't able to come up with a useful definition for it, and don't think it adds value for us right now.
Comment 6•13 years ago
|
||
(In reply to Will Bamberg [:wbamberg] from comment #5)
> (In reply to Irakli Gozilalishvili [:irakli] [:gozala] [@gozala] from
> comment #4)
> > This pull request adds metadata to a missing modules.
> >
> > Zer0 is right about content/content-proxy it's not a module.
> >
> > >
> > > * we sort of agreed (I thought: https://blog.mozilla.org/addons/2012/10/01/a-
> > > lifecycle-for-the-add-on-sdks-apis/) that we'd not use "unstable", (using only
> > > "experimental", "stable", and "deprecated") but many modules use it. I think
> > > these should be changed to "experimental".
> > >
> >
> > I don't recall that to be honest & I believe modules end up with metadata
> > that we
> > end up putting into spreadsheet. I can be convinced that we should change to
> > experimental if there were any reason for that.
>
> After we made the spreadsheet, I wrote up the API lifecycle in a blog post:
> https://blog.mozilla.org/addons/2012/10/01/a-lifecycle-for-the-add-on-sdks-
> apis/ and while doing that I thought just three categories would be
> sufficient, I emailed you, Jeff, and Mossop about it. Although I only got a
> positive answer from Mossop, I got no dissent from anyone else.
>
> The reason is simple: there's no distinction we can make between "unstable"
> and "experimental" that's actually useful to developers. We basically define
> the categories like:
>
> "experimental": can change without going through deprecation
> "stable": can only change if we go through deprecation
> "deprecated": will be removed/changed shortly, do not rely on it
>
> For each category, the contract with developers is clearly defined. Where
> does "unstable" fit in? If it can change without going through deprecation,
> how is this really different to "experimental"? Is it somehow "more stable"?
> But what does that even mean, what does it usefully communicate to
> developers? What's the specific payload of "more stable", if it's not
> getting the deprecation treatment that actually stable modules get?
>
> To be clear, I don't really mind if we have unstable. But I wasn't able to
> come up with a useful definition for it, and don't think it adds value for
> us right now.
I think we added metadata to the modules before that blog post, so that explains why we had a mismatch. I remember that post although I could have misunderstood it, I though message was that mostly our modules use these three flags not that it's the only flags we could use.
That being said I don't really have strong feelings about this either way if you
think we should change from unstable to experimental feel free to do that. As of descriptions to the flags I though we just adopt meaning that node uses:
http://nodejs.org/api/documentation.html#documentation_stability_index
The stability indices are as follows:
0 - Deprecated This feature is known to be problematic, and changes are planned. Do not rely on it. Use of the feature may cause warnings. Backwards compatibility should not be expected.
1 - Experimental This feature was introduced recently, and may change or be removed in future versions. Please try it out and provide feedback. If it addresses a use-case that is important to you, tell the node core team.
2 - Unstable The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable. Backwards-compatibility will be maintained if reasonable.
3 - Stable The API has proven satisfactory, but cleanup in the underlying code may cause minor changes. Backwards-compatibility is guaranteed.
4 - API Frozen This API has been tested extensively in production and is unlikely to ever have to change.
5 - Locked Unless serious bugs are found, this code will not ever change. Please do not suggest changes in this area; they will be refused.
In my mind there is a difference between experimental and unstable:
experimental - We're playing around with idea and we'll see which API makes sense and weather we can support it. Use it only if you don't mind updating later.
unstable - This API is ready to become stable we just wanna wait for some so you
can test it properly and we're sure no API issues are discovered. It unlikely for
us to change this and we'll do only if real problems are discovered.
That being said I can't really tell weather it's worth having this distinction in SDK, it's being useful in nodejs, but does not means it will be for us.
As I said I don't have strong opinions about this, if you think having three flags is better feel free to do that.
Comment 7•13 years ago
|
||
Commit pushed to master at https://github.com/mozilla/addon-sdk
https://github.com/mozilla/addon-sdk/commit/97e2f9a60fee81b851365647daaf9b1b9a7c4dde
Merge pull request #660 from Gozala/bug/missing-metadata@811960
Bug 811960 - Fix / Add missing module metadata
| Reporter | ||
Comment 8•13 years ago
|
||
Comment on attachment 683699 [details]
Pointer to Github pull request: https://github.com/mozilla/addon-sdk/pull/660
This looks good, and I've merged it.
Will we add a test that all modules have valid stability values as part of this bug? Also, I do think we might as well change unstable->experimental, if you're OK with that, and we should do so as part of this bug. I'm happy to do that part, but I'm not familiar enough with the test framework to write the test.
Attachment #683699 -
Flags: review?(wbamberg) → review+
| Reporter | ||
Comment 9•13 years ago
|
||
This changes "unstable" to "experimental". I'll leave it up to you if you want to merge it or not :).
Attachment #683791 -
Flags: review?(rFobic)
Updated•13 years ago
|
Status: NEW → RESOLVED
Closed: 13 years ago
Resolution: --- → FIXED
Comment 10•13 years ago
|
||
Comment on attachment 683791 [details]
pull request pointer
Leaving as is now since you don't seem to feel strongly about it and in my mind diff between unstable and experimental still makes sense.
Attachment #683791 -
Flags: review?(rFobic)
You need to log in
before you can comment on or make changes to this bug.
Description
•