1035969 - Document jpm

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect, P1)

Description

[Will Bamberg [:wbamberg]]

We need to update the Add-on SDK docs for jpm. This needs to include explaining to people how to port from cfx.

Comment 1

[Erik Vold [:erikvold] (please needinfo? me)]

Some source material:

* https://github.com/mozilla/addon-sdk/blob/JEP/JPM.md
* https://github.com/mozilla/jpm
* https://www.npmjs.org/package/jpm
* http://work.erikvold.com/jetpack/2014/07/08/jpm-beta.html

Comment 2

[Will Bamberg [:wbamberg]]

Here's all the stuff that will need doing for this bug:

1. new "Installation" tutorial
2. new "Getting Started" tutorial
3. new "jpm reference"
4. a guide to porting from cfx to jpm
5. update all the places in the tutorials where we refer to cfx

I think initially we'd make this a parallel set of docs for early adopters, keeping the cfx docs in place but adding pointers to the 'jpm side' for people who are interested. For (5), I don't think we should update the tutorials yet, we should just add a little banner pointing people at the jpm docs as an alternative. Then when jpm is released we should update all the tutorials, and make the jpm docs the primary reference, pointing to the cfx docs as a deprecated tool.

Comment 3

[Will Bamberg [:wbamberg]]

Here are four new pages, please consider this a review request without an attachment:

jpm reference:
https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm

cfx to jpm (please pay special attention to lists of things that have been removed here):
https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/cfx_to_jpm

Getting Started (jpm edition)
https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Getting_Started_%28jpm%29

Using 3rd party modules (jpm edition)
https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Using_third-party_modules_%28jpm%29

I haven't, yet, added little banners all over the place pointing people at jpm, but I think I should. Then there will be quite a lot of other places to update, but I think maybe that can wait until we're happy taking the "experimental" tag off jpm and calling it the mainstream way to develop.

Comment 4

[Jordan Santell [:jsantell] [@jsantell]]

JPM Documentation:
* Looks like the flags for `jpm xpi` is formatted a bit weird
* Some extra flags for testing are missing (in email I just sent you though!)
* Note that `jpm xpi` ignores tests files (things in the ./tests directory), as well as zip/xpis in PWD.

JPM to CFX
* In "requiring local modules", you use the jpm case before using the cfx case; previously on the page, the inverse is true (cfx, then, jpm) -- was a little weird while reading it!
* All the permanently removed commands look good -- if we decide to add any more in the future, it's something we haven't resolved/agreed upon yet
* check-memory and profile-memory are added as far as I can see on the jpm side

Getting Started
* looks great!

3rd party modules
* also good!

ni?ing Erik as well on his feedback

Comment 5

[Will Bamberg [:wbamberg]]

Thanks Jordan.

> * check-memory and profile-memory are added as far as I can see on the jpm

What sort of output do these give me? I ran with these and don't see and didn't see any extra output.

Comment 6

[Jordan Santell [:jsantell] [@jsantell]]

I'm not sure on those two -- I was never able to get them working (even in cfx) and thought they were only for tbpl. Irakli or Erik implemented it in jpm, do these actually work?

Comment 7

[Will Bamberg [:wbamberg]]

Thanks for the review Jordan.

(In reply to Jordan Santell [:jsantell] [@jsantell] from comment #4)
> JPM Documentation:
> * Looks like the flags for `jpm xpi` is formatted a bit weird
> * Some extra flags for testing are missing (in email I just sent you though!)
> * Note that `jpm xpi` ignores tests files (things in the ./tests directory),
> as well as zip/xpis in PWD.
> 

I've done these.

> JPM to CFX
> * In "requiring local modules", you use the jpm case before using the cfx
> case; previously on the page, the inverse is true (cfx, then, jpm) -- was a
> little weird while reading it!

Hm, I left this as it is: the 'jpm case' actually works with cfx too, and was already the preferred way to do things with cfx (as I understand it). So I though it better to say: the recommended approach still works, but by the way, there was this deprecated approach with cfx, that no longer works.

> * All the permanently removed commands look good -- if we decide to add any
> more in the future, it's something we haven't resolved/agreed upon yet
> * check-memory and profile-memory are added as far as I can see on the jpm
> side
> 

I've omitted these until we can give sensible guidance on what they actually do :).

Comment 8

[Erik Vold [:erikvold] (please needinfo? me)]

I'd like to take a look at this but I won't be able to between now and the end of my pto on oct 13th.

Comment 9

[Will Bamberg [:wbamberg]]

I'm closing this, since the docs are written and have been reviewed. I expect there will be some updates due by now, but let's please deal with them in a new bug.