Packages 1.1 Draft

[Mikeal Rogers]

I went ahead and wrote up most of the discussed issues from the "Packages 1.0 comments" thread in to a new draft proposal for Packages 1.1.

http://wiki.commonjs.org/wiki/Packages/1.1

The changes from 1.0 so far are:

* bugs property is optional
* added disclaimer to license property.
* repositories is now optional
* dependencies is now optional
* keywords are now optional
* contributors is now optional
* added minimal package example
* added overlay property
* added reserved properties for package registries: id, type, all properties beginning in _ and $

http://wiki.commonjs.org/index.php?title=Packages/1.1&action=history

Open issues are:

* clarification of directories property. It is currently unclear what implications the directories property has for a compliant packager (exclude other directories? recursively parse defined directories?)
* clarification, possibly removal, of "builtin" property (how is this enforced? should an installer override this if the package is clearly not a builtin? What is the use case?)

The most contentious issue seems to be the version range descriptions. I'll be creating a new email thread about that so please refrain from discussing that in this one, all other issue with the current changes or new additions are encouraged in this thread.

-Mikeal

[Kris Kowal]

On Wed, Mar 24, 2010 at 3:28 PM, Mikeal Rogers <mikeal...@gmail.com> wrote:
> The changes from 1.0 so far are:
> * bugs property is optional
> * added disclaimer to license property.
> * repositories is now optional
> * dependencies is now optional
> * keywords are now optional
> * contributors is now optional
> * added minimal package example
> * added overlay property
> * added reserved properties for package registries: id, type, all properties
> beginning in _ and $
> http://wiki.commonjs.org/index.php?title=Packages/1.1&action=history

This looked good to me.

>
> Open issues are:
>
> * clarification of directories property. It is currently unclear what
> implications the directories property has for a compliant packager (exclude
> other directories? recursively parse defined directories?)

It's my understanding of the "directories" property is that it has no
implications for a packager. In Narwhal, we have a "lean" property
which has "includes" and "excludes" and glob patterns, which we use
for packaging distributions. We use our analog for the "directories"
property to assist tools in finding relevant directories for
particular kinds of content, in case it isn't in the conventional
location. For example, by convention, we add the package's "lib"
directory to require.paths, topologically sorted with the "lib"
directories of all other packages based on the dependencies. We also
add all the ".jar" files in the "jars" directory of each package to a
URLClassLoader when running under Java, again topologically sorted
based on the package dependencies. If a package does not place their
".jar" and ".js" files in their conventional locations, they can be
overridden with the "directories" mapping. We also generally permit
multiple "lib" or "jars" directories if an Array is provided.

I think there is a hypothetical API that permits the user to ask a
package where its X directory is. If X is in directories, it returns
the corresponding value, normalized to an Array if it is a String. If
X is not in directories, it returns [X].

> * clarification, possibly removal, of "builtin" property (how is this
> enforced? should an installer override this if the package is clearly not a
> builtin? What is the use case?)

I'm indifferent about this. The existence of this property
presupposes that the package system has a means of distinguishing
packages designed to be overlaid on require.paths from packages that
link their lib directory into a location in one of the require.paths.
Since we do not have a clear picture about how we'll resolve this
issue, the semantics of the "builtin" property are limited to an
informative role at the moment.

> The most contentious issue seems to be the version range descriptions. I'll
> be creating a new email thread about that so please refrain from discussing
> that in this one, all other issue with the current changes or new additions
> are encouraged in this thread.

Since it's been a while, it might be good to kick off a new thread
with a summary of the results and perspectives of the previous.

Kris Kowal