Closed Bug 811960 Opened 13 years ago Closed 13 years ago

Fix module metadata

Categories

(Add-on SDK Graveyard :: General, defect, P2)

defect

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".
Blocks: 786286
`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)
`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").
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!
(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.
(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.
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
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+
Attached file pull request pointer —
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)
Status: NEW → RESOLVED
Closed: 13 years ago
Resolution: --- → FIXED
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.

Attachment

General

Created:
Updated:
Size: