559238 - Investigate bundling example packages, modules, and programs with the SDK

Status: RESOLVED FIXED

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

Description

[Drew Willcoxon :adw]

As we discussed briefly at the end of today's meeting, examples of high-level API usage would be helpful for people learning the SDK, especially as we ramp up the APIs.

I was thinking of real, runnable examples being bundled in each release, for these reasons:

* Examples live with the code and Markdown docs, no website
  lookup required.

* They can be run and built directly from the command line.  cfx
  could provide automated support.

* They can be easily copied to new files and tinkered with.

Should examples be packages, modules, or programs?  Where in the tree should they live?

* A top-level examples directory with no particular structure.

* Modules per example, e.g.:
  jetpack-sdk/packages/examples/lib/example1.js

* Packages per example, e.g.,
  jetpack-sdk/packages/examples/packages/example1

* Example modules per package, e.g.,
  jetpack-sdk/packages/jetpack-core/examples/example1.js

* Example packages per package, e.g.,
  jetpack-sdk/packages/jetpack-core/packages/example1

I like the per-package approach, since it lets anyone anywhere who writes a package share examples with it -- the same way they can share docs.  But Myk pointed out that cross-API examples are useful too.

Comment 1

[Myk Melez [:myk] [@mykmelez]]

(In reply to comment #0)
> I like the per-package approach, since it lets anyone anywhere who writes a
> package share examples with it -- the same way they can share docs.  But Myk
> pointed out that cross-API examples are useful too.

Cross-API examples would be useful, but the ability to share per-package examples like you share per-package docs and tests seems really valuable, so I would start there and table cross-API examples for now.

Of the two per-package options, packages seem preferable, since developers can more easily copy one to use as a base for a new extension.  I'm worried about the directory structure being complicated and hard to understand, though, if we put examples in a generic "packages" directory.

I wonder if it would be possible to do something like this:

  jetpack-sdk/packages/jetpack-core/examples/example1

... where "examples" is understood to be a directory of packages and "example1" is a package.

Comment 2

[Drew Willcoxon :adw]

Cool, that sounds OK to me.  About cross-API examples, if examples are packages, they can include other packages in their list of dependencies and use any APIs they want.  (If they're not packages, whatever package they're in can do the same thing.)

Comment 3

[Atul Varma [:atul]]

Yeah, I really like Myk's suggestion.

Putting examples in the generic 'packages' directory, which is already reserved for a package's sub-packages [1], would make it hard to figure out which packages were meant as examples and which were intended as reusable code, both for users and cfx docs (we wouldn't want example packages listed in the sidebar alongside e.g. jetpack-core, for instance).

So it sounds like this doesn't actually *require* any changes in the code, right? It's mostly just a custom/standard that we'd like others to follow, by setting the example and making 'examples/' in our own packages?

Ultimately, it'd be nice for the doc server to automatically present the examples and let the user read and browse their source easily, but those don't seem like blockers.

Also, we should probably make sure that 'cfx testall' actually runs any tests in example packages too, if they're present.  And actually, since many of the packages are intended to ultimately represent extensions, they'd make excellent integration test cases for MozMill, which I wrote about a bit more in bug 559306 comment 3.

[1] https://jetpack.mozillalabs.com/sdk/0.2/docs/#guide/package-spec

Comment 4

[Myk Melez [:myk] [@mykmelez]]

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".

Comment 5

[Myk Melez [:myk] [@mykmelez]]

It feels like this is fixed, given that we now have an examples/ directory and some example addosn (although we could always use more and different kinds!).