Writing a Package about guide HOT 17 CLOSED

This is one-half of the proposed package guide. This one will related just to building packages, while the other will talk about sharing them with the community.

Meteor guide: Building a great package

1. Creating a simple package and publishing it
2. How to deliver different code for different platforms and architectures
3. How to integrate an existing Cordova plugin or write your own
4. How to test your package
5. How make a build plugin
   1. Compiling single files into other single files
   2. Compiling many files at once that can be inter-related

from guide.

A lot of these things basically aren't documented anywhere. There's a start on the content already, which has some of these bullet points.

I don't think there are any research topics here, since MDG has been building packages since the dawn of time. It's more about explaining how the thing works in one place.

Opinions

1. A package should export only one symbol if at all possible (except for templates) - there is some discussion about this in the app structure issue: #9
2. Testing should probably be done via mocha/jasmine if at all possible, which is a much more complete testing framework than tinytest. I've heard the velocity folks have something for this. Also, I don't know if package testing goes here or in the testing chapter; probably testing? @tmeasday what do you think?

Things to mention that aren't in the outline

1. How to use transpiled languages in a package
2. How to make a good package that includes importable LESS/SCSS files

from guide.

One more thing: have a standard organization for package.js, as suggested by @mitar here: #9 (comment)

from guide.

I think package testing is probably the main thing we'll talk about in the testing chapter TBH, so I guess it goes there.

from guide.

Posted an outline: #60

from guide.

hey Guys

Something I'm a little confused about and struggling to find clarity on is around the meteor core dependencies for a package, which we've basically guessed at with varying success until now, and it would be really great to have an exact, specific and clear reference for that.

If I've missed it I apologize, but I haven't seen this anywhere and have dug around in other packages to see what they're doing. I think it would be a great addition to this article.

from guide.

@stubailo @tmeasday Hey Guys,

any thoughts on the above? would be really helpful, a) if this already out there to know, or if you would consider including some info about it in the outline for the guide article.

from guide.

Ah, sorry for not responding.

I think it's a pretty unfortunate situation that it's not clear where different symbols come from, and it's not clear what packages you need to get them. The best you can do is probably search the code of the Meteor repository for api.export, or look at the source code link in the docs to see what package it's defined in.

In Meteor 1.3, there will be an option to import stuff from packages, for example: import { ReactiveDict } from 'meteor/reactive-dict'. In order to make this feasible, we'll need to start documenting which symbols come from which packages, which should resolve your issue.

@benjamn, what do you think? I don't think it would be hard to add an annotation for JSDoc to indicate which module you import a certain symbol from.

from guide.

Hey, @stubailo, thanks for the feedback, to have a full list would be awesome, but to have even a interim reference to the most commonly used ones for package authors would be incredibly helpful.

While I'm looking forward to the increased control with imports, I am also a fan of packages with one specific export. Overall 1.3 should bring a lot with it. Can't wait.

from guide.

@stubailo I've just looked over this content with a view to figuring out what to include in the 1.3 launch.

Here's my plan, I welcome your thoughts:

1. Rewrite intro, basically only point 3 applies
2. Leave out api.onTest and meteor test-packages [or a very brief section on it?]
3. Rewrite the adding files / exporting to be basically "use api.mainModule(), import and export from there"
4. Maybe just remove the bit about imply? Not quite sure what's best here
5. Leave the stuff about dependencies / semvar / less / cordova
6. Rewrite the NPM stuff to talk about Npm.depends(), "peer" dependencies, and how to import.
   1. Move the stuff about how to consume NPM packages (i.e. the promises bit) to the "using packages" article and link to it here.
   2. Remove stuff about how to "synchronize" call-back based APIs. [I'll have something about using callback-based APIs in methods in i) above]
7. Leave remaining sections with some minor re-working

from guide.

Sure, if you think it's valuable, we can do that. But I think mentioning test-packages would be a good idea. It's not that much content, right? you just pass a driver package and add some files/packages in onTest?

from guide.

Sure, if you think it's valuable, we can do that

Do you mean the entire article? We kind of need to do it for section 6. above -- this info is not really available anywhere else.

But I think mentioning test-packages would be a good idea. It's not that much content, right? you just pass a driver package and add some files/packages in onTest?

Sure!

from guide.

Personally I think this article is less useful than some others, do you think there is a way we could get more community input on this one? Perhaps there are people who have already written about how to write packages.

Also, we will eventually need a guide about how to write NPM packages, would that be in this article or a different one?

from guide.

I guess it would be this article.

The only real reason we need to do this article for 1.3 is section 6. Perhaps I should just do that and cut the other content? It seems kind of odd though, given you've written half of it..

from guide.

Yeah but I feel like putting it in the actual guide means we are standing behind that content and maintaining it. Perhaps there is a better place, like the blog or something? IDK if we feel like we want to maintain this article and later morph it into the NPM version then it is probably worth it.

from guide.

Another approach would be to include the peer NPM info (and some of what appears here: http://docs.meteor.com/#/full/writingpackages) in the docs, perhaps here: http://docs.meteor.com/#/full/packagejs

Then again, if there are slabs of content (however small) I think it probably makes sense to just do a guide article. I think just a very short version of this article is the way to go.

from guide.

OK, sounds good to me!

from guide.