616640 - make cfx init provide only the skeletal infrastructure for an addon

Status: RESOLVED FIXED

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

Description

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

Sample files may be useful the first time you build an addon, but they're not as useful afterwards, and cfx init is intended to be a tool you use to initialize every addon you create, so it should provide only the skeletal infrastructure for a functional addon, and we should direct users to the examples directory for more fleshed out examples.

Also see bug 613630, which is about moving cfx init's templates into the examples directory to make them easier to modify.

Comment 1

[Atul Varma [:atul]]

Some additional argument for this bug is voiced by will bamberg in bug 613579 comment 1.

I'm also CC'ing warner on this, because I think it was originally his idea to have "cfx init" provide the sample code. I'm trying to find the specific bug number about it, but it's eluding me.

I agree with this bug, though--I've used 'cfx init' once and had to delete a bunch of the sample code it made too.

Comment 2

[Atul Varma [:atul]]

Oh, and the only reason I haven't used 'cfx init' more than once is because I decided it was easier to just manually create an addon from scratch than to manually delete all that auto-generated sample code. :)

Comment 3

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

(automatic reprioritization of 1.0 bugs)

Comment 4

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

(Pushing all open bugs to the --- milestone for the new triage system)

Comment 5

[Alexandre Poirot [:ochameau]]

Attachment: Pull request 369

I still generate files, but empty!
Except for unit test where I let require("main") and a single test function.
Do you think that make sense, or should we just generate all directory and only package.json file?

Comment 6

[Brian Warner [:warner :bwarner]]

Comment on attachment 604247 [details]
Pull request 369

I've got mixed feelings about emptying all the files: I'll defer to the
experience of Myk and Atul (and others) about the value of starting with an
example versus starting with less. But if we want to go that way, this patch
seems fine.

I'm cool with recognizing that a verbose "skeleton" addon is only appropriate
for the very first few times you run "cfx init" (and might be better served
with a "cfx init --helloworld" or "cfx init --sample=helloworld" or some
other "please give me a sample to start from" option).

I guess the criteria for non-educational uses of "cfx init" should be how
much editing you have to do afterwards: are there contents which are pretty
much present in all addons? Or are there conventions we want to encourage
that would be helped by putting some guidelines/samples into the skeleton?
For example, if we want to encourage writing unit tests, having
test/test-main.js is a good start. If we didn't care about that, we could
leave out the whole test/ directory (the argument, which I don't quite buy,
is "well, the docs explain how to add tests if you want them anyways"). I
think we *do* want to encourage using tests, which means that we should
include as much common code in the skeleton as we can (without adding too
much that will need to be deleted later). The proposed test-main.js seems to
do that: it might nudge some users into feeling like they should explore and
enhance the existing file, whereas if the file (or the directory) doesn't
exist, they'd have to be pretty motivated to add it.

Docs are a similar example, but the skeleton file is less useful: how much
can you say about a generic addon? I think it's like the way that some
projects I've seen with config files that you're supposed to edit before use
(I think Apache, maybe a few MTAs like Postfix), which default to something
like "The admin of this site is lazy and hasn't bothered to edit their config
files", so when you visit the site or whatever, at least you see something
that's accurate instead of generic or an example. If our skeleton docs said
"this is the great Hello World addon", then it'd be misleading when someone
uses "cfx init" and writes a great addon but just forgets to modify the docs.
If they say "this is where you write the docs for your addon", then they'd
still be unhelpful but at least not outright wrong.

Eh, not a big deal, really :). So, I'm r+, but I'd suggest somebody think
about these issues briefly and see if removing all this content meets our
goals.

Comment 7

[Alexandre Poirot [:ochameau]]

Comment on attachment 604247 [details]
Pull request 369

Brian, your concern makes sense. I didn't took much time to think about this. I just throw a pull request in order to make thinks move in this "old" bug and to help Will in his documentation effort.

Will, I'd like to get your feedback on this patch, as I've done it regarding your comment in tutorial pull request (about `const` usage in cfx init code).

I'm wondering if it makes sense to flag this bug for triage? Just to ensure some discussion on relevance of this bug?

Comment 8

[Will Bamberg [:wbamberg]]

I agree that asking for triage is worthwhile, and that Brian raises some valid concerns.

To me, this sample code isn't particularly useful. Yes, it's nice to have a functional add-on right from the start, but I don't expect anyone to run "cfx init" for the first time outside the context of a "getting started" tutorial, which will provide sample content to include.

So to me, the main use of cfx init is "non-educational", and it's primarily to create the package.json (which reminds me, it should also create the program ID unless --programid="something@somewhere" is specified).

But that's very much my perspective - I create lots and lots of small add-ons to demonstrate stuff, and have to delete the sample code every time, so this is very visible to me. I'd guess most add-on developers don't care much either way.

> I guess the criteria for non-educational uses of "cfx init" should be how
> much editing you have to do afterwards: are there contents which are pretty
> much present in all addons? Or are there conventions we want to encourage
> that would be helped by putting some guidelines/samples into the skeleton?
> For example, if we want to encourage writing unit tests, having
> test/test-main.js is a good start. If we didn't care about that, we could
> leave out the whole test/ directory (the argument, which I don't quite buy,
> is "well, the docs explain how to add tests if you want them anyways"). I
> think we *do* want to encourage using tests, which means that we should
> include as much common code in the skeleton as we can (without adding too
> much that will need to be deleted later). The proposed test-main.js seems to
> do that: it might nudge some users into feeling like they should explore and
> enhance the existing file, whereas if the file (or the directory) doesn't
> exist, they'd have to be pretty motivated to add it.

I'd agree about that.

> Docs are a similar example, but the skeleton file is less useful: how much
> can you say about a generic addon? I think it's like the way that some
> projects I've seen with config files that you're supposed to edit before use
> (I think Apache, maybe a few MTAs like Postfix), which default to something
> like "The admin of this site is lazy and hasn't bothered to edit their config
> files", so when you visit the site or whatever, at least you see something
> that's accurate instead of generic or an example. If our skeleton docs said
> "this is the great Hello World addon", then it'd be misleading when someone
> uses "cfx init" and writes a great addon but just forgets to modify the docs.
> If they say "this is where you write the docs for your addon", then they'd
> still be unhelpful but at least not outright wrong.

In the current setup the docs (both README.md and the contents of doc/) are more of a tool for package developers than for add-on developers.

* If I write a reusable package and document it using README and doc/, then these docs show up in the browser when a developer "installs" my package (and the tutorial for creating reusable modules explains this feature, so for this purpose, having sample files isn't important).

* If I write an add-on, and document it using README.md and doc/my-addon.md, then those docs won't be readily consumable by my users. 

I imagine the presence of these files could be confusing for add-on developers, suggesting that if they document their add-on here, the documentation will be built into the XPI and be consumable by their users (as, for example, the text displayed in the Add-on Manager page?). Perhaps it should?

Comment 9

[Alexandre Poirot [:ochameau]]

Looks like we all kind of agreed that init templates are bad in current shape.

But it is still unclear if my current patch is:
* Good enough:
Just land it and mark it as resolved fixed

* A good iteration before providing better content.
Let simplify like this, and open follow-up bugs.
What would be their title?

* Not enough:
We should get rid of `doc`/README.md too (for ex)?
We should provide a incitative content to write unit tests.

Comment 10

[[github robot]]

Commits pushed to master at https://github.com/mozilla/addon-sdk

https://github.com/mozilla/addon-sdk/commit/b72608c3e49d1a06be41ade64271bbeb3938230f
Bug 616640: make cfx init provide only the skeletal infrastructure for an addon

https://github.com/mozilla/addon-sdk/commit/7c24e7acc2eaef973742b85bc9e3b89f8cc76299
Merge pull request #369 from ochameau/bug-616640-clean-cfx-init

Bug 616640: make cfx init provide only the skeletal infrastructure for an addon r=@warner

Comment 11

[Alexandre Poirot [:ochameau]]

I finally landed the reviewed patch, feel free to open followup bug if there is still improvement to be done.