Restructure package/module structure and/or reference documentation to make more sense to Addon developers

RESOLVED DUPLICATE of bug 592848

Status

RESOLVED DUPLICATE of bug 592848
9 years ago
8 years ago

People

(Reporter: avarma, Assigned: avarma)

Tracking

Firefox Tracking Flags

(Not tracked)

Details

(Assignee)

Description

9 years ago
It's currently very difficult to understand what modules are relevant and which are irrelevant for Addon developers:

  https://jetpack.mozillalabs.com/sdk/0.4/docs/

For instance, 'xhr' and 'page-worker' are useful to addon developers, but 'observer-service' is only of use to Jetpack Platform developers, yet they're all jumbled into the same place in the docs.

One solution is to separate different modules into new packages, e.g. 'jetpack-core-chrome' and 'jetpack-core', but there are actually some modules that fit into both categories. IA-wise, it seems like tagging might make more sense here.
(Assignee)

Updated

9 years ago
Assignee: nobody → avarma
Status: NEW → ASSIGNED
(Assignee)

Comment 1

9 years ago
While I haven't yet come up with a solid proposal, and all the things I've thought of so far would involve a lot of work and restructuring, I have a stop-gap measure that will at least make it easier for developers to make sense of our documentation for the imminent FlightDeck and Jetpack SDK releases.

This is simply to add a header to the .md documentation for all "low-level" modules--that is, modules which are irrelevant to addon developers--that mentions the module is low-level and not intended for use by addon developers.
(Assignee)

Comment 2

9 years ago
It looks like only the jetpack-core package contains any modules that addon developers would really care about--the development-mode, nsjetpack, and test-harness packages are all supporting infrastructure for the Jetpack platform and toolchain.

Within jetpack-core, these modules would be of interest to addon developers:

* xhr
* collection
* context-menu
* page-worker
* private-browsing
* self
* simple-storage
* timer
* unit-test
* widget

And these either wouldn't be of interest, or carry so much authority with their use that we'd much rather developers use alternatives (e.g. simple-storage instead of file):

* api-utils
* byte-streams
* cuddlefish
* errors
* file
* memory
* observer-service
* plain-text-console
* preferences-service
* securable-module
* tab-browser
* text-streams
* traceback
* unload
* url
* window-utils
* xpcom
* xul-app
(Assignee)

Comment 3

8 years ago
Another option I discussed with Myk is labeling the second list above as "private implementation" files, signified by moving them into a directory called "private", so that importing e.g. tab-browser would be doing via require("private/tab-browser").  The advantage of this is that not only will add-on developers know not to look there, but we'll also have a bit more social freedom to change the interfaces of the private modules if necessary--that is, changing an API for a private module won't be terribly unexpected, while changing the API of a public one would be.
I like the option described in comment 3.

I also think we should rename "jetpack-core" to "core" in the process of making this change.
OS: Mac OS X → All
Priority: -- → P1
Hardware: x86 → All
Target Milestone: -- → 0.8
Erm, the 0.8 deliverable is actually bug 592848 (although it's possible that this bug will get fixed in the process of fixing that one, if we decide to merge the concepts of "private" and "low-level" in the process of fixing that bug).
Priority: P1 → --
Target Milestone: 0.8 → --
Depends on: 592848
(Assignee)

Comment 6

8 years ago
The current plan for this is to fix bug 596089, "Distinguish between high and low-level packages", and then move all the low-level modules in jetpack-core out into a low-level package.
(Assignee)

Updated

8 years ago
Depends on: 596406
No longer depends on: 592848
(Assignee)

Comment 7

8 years ago
I'm going to go ahead and file this as a duplicate of bug 592848.
Status: ASSIGNED → RESOLVED
Last Resolved: 8 years ago
Resolution: --- → DUPLICATE
Duplicate of bug: 592848
The Add-on SDK is no longer a Mozilla Labs experiment and has become a big enough project to warrant its own Bugzilla product, so the "Add-on SDK" product has been created for it, and I am moving its bugs to that product.

To filter bugmail related to this change, filter on the word "looptid".
Component: Jetpack SDK → General
Product: Mozilla Labs → Add-on SDK
QA Contact: jetpack-sdk → general
Version: Trunk → unspecified
You need to log in before you can comment on or make changes to this bug.