I've mined the various information and pulled together a proposal for
Packages 0.1. This proposal defines the package.json file, the package
directory structure and package file format. It does not specify the
catalog file (yet).
I'd like to get feedback on this so we can iterate and then nail down
this part of the packaging system. Then we can all create packages
with confidence they will be usable in the various package managers,
tools and loaders.
I've tried to collect the various input from all, but I've also added
a couple of new fields. Please point out any fields that are missing
from the descriptor file.
I've kept the package.json file fairly flat to make it easier for
tools to inspect and modify fields.
> I've mined the various information and pulled together a proposal for
> Packages 0.1. This proposal defines the package.json file, the package
> directory structure and package file format. It does not specify the
> catalog file (yet).
> I'd like to get feedback on this so we can iterate and then nail down
> this part of the packaging system. Then we can all create packages
> with confidence they will be usable in the various package managers,
> tools and loaders.
> I've tried to collect the various input from all, but I've also added
> a couple of new fields. Please point out any fields that are missing
> from the descriptor file.
> I've kept the package.json file fairly flat to make it easier for
> tools to inspect and modify fields.
> I've mined the various information and pulled together a proposal for
> Packages 0.1. This proposal defines the package.json file, the package
> directory structure and package file format. It does not specify the
> catalog file (yet).
> I'd like to get feedback on this so we can iterate and then nail down
> this part of the packaging system. Then we can all create packages
> with confidence they will be usable in the various package managers,
> tools and loaders.
> I've tried to collect the various input from all, but I've also added
> a couple of new fields. Please point out any fields that are missing
> from the descriptor file.
> I've kept the package.json file fairly flat to make it easier for
> tools to inspect and modify fields.
> I've mined the various information and pulled together a proposal for
> Packages 0.1. This proposal defines the package.json file, the package
> directory structure and package file format. It does not specify the
> catalog file (yet).
> I'd like to get feedback on this so we can iterate and then nail down
> this part of the packaging system. Then we can all create packages
> with confidence they will be usable in the various package managers,
> tools and loaders.
> I've tried to collect the various input from all, but I've also added
> a couple of new fields. Please point out any fields that are missing
> from the descriptor file.
> I've kept the package.json file fairly flat to make it easier for
> tools to inspect and modify fields.
> Enjoy
> --mob
What are the differences between categories and keywords? And do we really need either?
Author: being a single field - split it into three (or an array of 3 elements) rather than requiring a fixed format that people will inevitably get wrong (and then only the name of the 3 is required).
Dependencies: not sure the version handling is right. if we are using semantic versioning then isn't just [ "ejs", "1.0.0"] enough and implies the >= part and "< 2.0" is implicit from SemVer. (I also don't like '>=' as it implies '=' should work and I really dont want to get into the culture of letting people do that)
stability: again, doesn't SemVer cover this and make it redundant?
checksum: why [ "md5", "valuehere" ] and not just { "md5": "valuehere" } - its not like you can have more than one checksum of a given type, and this would make access easier.
builtin: is this needed?
directories: purpose? And if its a hash what are the keys?
scripts: Hmmm I thought this was going to be list of scripts to install or some such. Perhaps "commands" or "build_commands" is a better name?
Haven't yet had time to think though and see if there is anything missing.
I agree that semantic versioning should alleviate the need for complex
version predicates, even in the case where someone breaks their API
accidentally; they can ramp their patch version and revert to fix the
problem.
Last Friday I did some work on Tusk's "tusk update" which adds support
for multiple catalog consolidation, and subsumes the responsibility of
"tusk create-catalog". It also embodies my latest set of
recommendations for the catalog schema.
> > I've mined the various information and pulled together a proposal for
> > Packages 0.1. This proposal defines the package.json file, the package
> > directory structure and package file format. It does not specify the
> > catalog file (yet).
> > I'd like to get feedback on this so we can iterate and then nail down
> > this part of the packaging system. Then we can all create packages
> > with confidence they will be usable in the various package managers,
> > tools and loaders.
> > I've tried to collect the various input from all, but I've also added
> > a couple of new fields. Please point out any fields that are missing
> > from the descriptor file.
> > I've kept the package.json file fairly flat to make it easier for
> > tools to inspect and modify fields.
> > Enjoy
> > --mob
> What are the differences between categories and keywords? And do we really
> need either?
> Author: being a single field - split it into three (or an array of 3
> elements) rather than requiring a fixed format that people will inevitably
> get wrong (and then only the name of the 3 is required).
+1
> Dependencies: not sure the version handling is right. if we are using
> semantic versioning then isn't just [ "ejs", "1.0.0"] enough and implies the
> >= part and "< 2.0" is implicit from SemVer. (I also don't like '>=' as it
> implies '=' should work and I really dont want to get into the culture of
> letting people do that)
> stability: again, doesn't SemVer cover this and make it redundant?
Does it? IIUC every release >= 1.0.0 is *stable*. That said I'm a little
apprehensive to support adding a stability flag to the core packages
standard as it would effectively augment the version number which could
complicate things.
> checksum: why [ "md5", "valuehere" ] and not just { "md5": "valuehere" } -
> its not like you can have more than one checksum of a given type, and this
> would make access easier.
I noticed quite a few things were tuples instead of hashes -- is there a
good reason for this?
I'll review now and throw more comments out there, but thanks for getting
the ball rolling and compiling this, mob.
> What are the differences between categories and keywords? And do we really need either?
Keywords are free form. I need something to do with "md5" or "jsgi".
Categories are used when creating a web portal for the packages. When
we have 5,000 packages, a portal can present various categories such
as: "System Tools", "Cryptography", "Web Templating".
> Author: being a single field - split it into three (or an array of 3 elements) rather than requiring a fixed format that people will inevitably get wrong (and then only the name of the 3 is required).
Okay. Sounds good.
> Dependencies: not sure the version handling is right. if we are using semantic versioning then isn't just [ "ejs", "1.0.0"] enough and implies the >= part and "< 2.0" is implicit from SemVer. (I also don't like '>=' as it implies '=' should work and I really dont want to get into the culture of letting people do that)
Yes, you can omit the upper bound version which implies 1.0.0 or
later. Sounds reasonable to omit the operator to mean ">=" for the
lower and "<=" for the upper. We could omit the operators and just
have 2 simple versions where the are:
LOWER <= VERSION <= UPPER
> stability: again, doesn't SemVer cover this and make it redundant?
Partially. There is quite a bit of legacy stuff not using SemVer. But
if folks are happy with SemVer, then it would be simpler to remove
"stability". I like simplicity.
> checksum: why [ "md5", "valuehere" ] and not just { "md5": "valuehere" } - its not like you can have more than one checksum of a given type, and this would make access easier.
Agree. Good pickup.
> builtin: is this needed?
It means you can't remove some packages. When a platform is installed,
it will typically contain many packages. These are intrinsic to the
platform. It is in the optional fields section. Most packages won't
use it.
> directories: purpose? And if its a hash what are the keys?
Ah, my last edit adding an example got deleted in the page rename.
I'll re-add that and it will be clearer.
> scripts: Hmmm I thought this was going to be list of scripts to install or some such. Perhaps "commands" or "build_commands" is a better name?
It is a list of scripts to run when installing, removing or building.
> Haven't yet had time to think though and see if there is anything missing.
> Last Friday I did some work on Tusk's "tusk update" which adds support
> for multiple catalog consolidation, and subsumes the responsibility of
> "tusk create-catalog". It also embodies my latest set of
> recommendations for the catalog schema.
Can we do the Catalog after we settle on the package.json format?
Since the catalogue depends so heavily on it.
Kris: could you identify which of your package.json fields should be
in this spec. Some are custom fields for Narwhal, but I'd like to get
a complete set of fields here. Can you identify any candidates I've
missed?
> Does it? IIUC every release >= 1.0.0 is *stable*. That said I'm a little
> apprehensive to support adding a stability flag to the core packages
> standard as it would effectively augment the version number which could
> complicate things.
It needs to be clean. But perhaps we can't achieve it cleanly. The
need is when I download a package into a production system, I'd like
to know if the developers think it is suitable for that. After a 1.0,
you could still have a period of rapid development where a package is
"evolving" and not suitable for production.
Versions are different, they are used for dependency resolution.
Stability is a guide to the user.
> > checksum: why [ "md5", "valuehere" ] and not just { "md5": "valuehere" } -
> > its not like you can have more than one checksum of a given type, and this
> > would make access easier.
> I noticed quite a few things were tuples instead of hashes -- is there a
> good reason for this?
Thanks. Ash picked this up too.
> I'll review now and throw more comments out there, but thanks for getting
> the ball rolling and compiling this, mob.
<ash_flusspf...@firemirror.com> wrote:
> What are the differences between categories and keywords? And do we really need either?
We should have keywords for "package-manager search keyword" commands,
like "pkgmgr search wiki markup". We might want to go so far as
having an evolving wiki page to recommend keywords for particular
types of services.
> Author: being a single field - split it into three (or an array of 3 elements) rather than requiring a fixed format that people will inevitably get wrong (and then only the name of the 3 is required).
Tusk normalizes author, maintainer, and contributor fields to a {name,
url, email} hash. A string of comma separated terms might suffice
with a parser that can distinguish a web page from an email. The
author hash might be extended with some sort of unique identifier like
a Github user name for package managers to ensure consistency of
author fields across packages.
> Dependencies: not sure the version handling is right. if we are using semantic versioning then isn't just [ "ejs", "1.0.0"] enough and implies the >= part and "< 2.0" is implicit from SemVer. (I also don't like '>=' as it implies '=' should work and I really dont want to get into the culture of letting people do that)
> stability: again, doesn't SemVer cover this and make it redundant?
It's my hope that semantic versioning reduces the need for version
predicates as well.
> checksum: why [ "md5", "valuehere" ] and not just { "md5": "valuehere" } - its not like you can have more than one checksum of a given type, and this would make access easier.
+1. Might consider "hash" or "signature".
> builtin: is this needed?
I haven't found a need for this qualifier. Might be well enough to
the implementations.
> directories: purpose? And if its a hash what are the keys?
This is intended to replace the top-level "lib", "bin", "docs", &c
properties that Tusk uses. I think it's fine to make a special name
space for these properties; we're on the verge of name conflicts in
Tusk. It should be emphasized that these are intended to override
default locations by the same names, and that an array should be
provided if there are multiple directories that contain that kind of
file, like {"directories": {"bin": ["bin", "sbin"]}}.
> scripts: Hmmm I thought this was going to be list of scripts to install or some such. Perhaps "commands" or "build_commands" is a better name?
+1 to scripts to forestall bike shedding if possible.
On Wed, Dec 16, 2009 at 1:46 PM, Dean Landolt <d...@deanlandolt.com> wrote:
> On Wed, Dec 16, 2009 at 4:38 PM, Ash Berlin <ash_flusspf...@firemirror.com>
>> On 16 Dec 2009, at 21:22, mob wrote:
>> Author: being a single field - split it into three (or an array of 3
>> elements) rather than requiring a fixed format that people will inevitably
>> get wrong (and then only the name of the 3 is required).
> +1
+/- 0
>> stability: again, doesn't SemVer cover this and make it redundant?
> Does it? IIUC every release >= 1.0.0 is stable. That said I'm a little
> apprehensive to support adding a stability flag to the core packages
> standard as it would effectively augment the version number which could
> complicate things.
Let's leave "stability" off. It's purely informational. We can take
care of "stable", "unstable", and "test" by providing different
catalogs that offer different versions. If someone wants to volunteer
what catalog they would like to be included in, we might need to do
this differently. I had considered possibly advertising a "versions":
{} property and "trains": {stable, unstable, test, dev} with alternate
sources. My brain exploded and I had to scale back. Unless someone
can write a thesis on this issue right now, I think we should table
it.
> I noticed quite a few things were tuples instead of hashes -- is there a
> good reason for this?
I've regretted using tuples instead of hashes on several occasions. I
advise the use of Objects for any structural data instead of having
position imply the label.
> I'll review now and throw more comments out there, but thanks for getting
> the ball rolling and compiling this, mob.
> * keywords - an Array of String keywords to assist users searching for the
package in catalogs.
+1
> * categories - an Array of String keywords to classify the package.
I think that we should wrap these into keywords and have catalog
maintainers encourgage consistency here.
> * author - Original or primary author of the package. Must be of the format:
> "Name (URL) <EMAIL>", where (URL) and <EMAIL> are optional but recommended. For
> example:
> "Bill Bloggs (http://www.bblogmedia.com) <billbl...@bblogmedia.com)
I think we should allow this format, comma delimited, and an Object format,
all of which would get normalized to the Object.
> * contributors - an Array of strings each containing the details of a
> contributor. Format is the same as for author.
+1
> * bugs - URL for submitting bugs. Can be mailto or http.
I'm thinking we should so something similar to author for this one, where
"url" and "email" can be specified, comma delimited, or (urled) and <emailed>.
> * license - array of licenses under which the package is provided. Each
> license is a tuple where the first element is the kind of license and the
> second element is a URL to the license. For example
> licenses: [["GPL",
> "http://www.ejscript.org/products/ejs/doc/licenses/gpl.html"]]
I'm thinking we should have a standard set of license names, and then allow an
Object for custom variants with {"name", "url"} objects instead of tuples.
> * location - Array of repositories where the package can be located. Each repository is a tuple where the first element is the kind of repository and the second element is a URL path to clone/checkout the package. For example:
> location: [["mercurial", "http://hg.embedthis.com/ejs"]]
I think we ought to leave this out for now since it's highly coupled to the
catalog specification, I think. In my latest work on Tusk, the catalog
consolidation system automatically adds a "source" property to the package
descriptor which is the source descriptor that was used to get the rest of the
information. It has a "type" field and the rest of its properties depend on
the VCS or whether a VCS was used at all.
> * dependencies - Array of prerequisite packages on which this package depends in order to install and run. Each dependency is an array with one to three elements. The first element is the dependent package name and is mandatory. The second is an optional version expression defining the lowest qualifying version. The third element is a version expression defining the highest qualifying version. Version expressions are of the form: operator SPACE version. For example:
> dependencies: [ "ejs", ">= 1.0.0", "< 2.0"].
It does need to be an array. For the simple case, I think a mere package name
should be permitted, and the version "" implied, which should accept anything.
For the complex case, it should be an Object with something like {name,
version} or {name, min, max} if you think that's critical.
> This specifies a dependency on the "ejs" package with versions between 1.0 and 2.0. If the version are omitted, the latest available version of the dependency is acceptable.
Let's reserve "example" as a package name much like the reserved "example.com",
although I *do* think you deserve the free advertising :P
> * conforms - Array of relevant CommonJS specifications this package supports. TBD: define these specifiers. For example:
> conforms: [ "CommonJS-Modules-1.0", "CommonJS-JSGI-1.0"]
I recommend "implements" and that the value be a URI of the specification,
perhaps identical to its URL. Perhaps alternately its Wiki page name in case
we move.
> Optional Keywords
> * homepage - URL string for the package web site
+0. We can migrate from "url". Doesn't really matter as long as "url" isn't
reserved for something else.
> * os - Array of supported operating systems. If absent or set to the empty set, the package makes no platform assumptions. TBD: specify leading OS names.
+1
> * cpu - Array of supported CPU architectures. If absent or set to the empty set, the package makes no platform assumptions. TDB: specify leading CPU architectures.
+1
> * builtin- Boolean value indicating the package is built in as a standard component of the underlying platform
-1. It's fine for this to be implied by dependency, I think.
> * directories - Object hash of package directories. Typical directories include "lib", "src", "doc", "test" and "bin". Package manager tools SHOULD use these directory definitions to find various package components.
+1
> * scripts - Object hash of scripts used in managing the package. A package manager tool may use these scripts to install, build, test or uninstall the package. For example:
> scripts: {
> install: "install.js",
> uninstall: "uninstall.js",
> build: "build.js,
> }
+1
> Package managers and loaders should ignore unknown fields in the package descriptor file.
If we make this a normative clause, we should aggressively reserve any words we
...
On Wed, Dec 16, 2009 at 2:10 PM, mob <m...@embedthis.com> wrote:
> Can we do the Catalog after we settle on the package.json format?
> Since the catalogue depends so heavily on it.
Yes, although a reference to the package descriptor schema should
suffice for that portion of the catalog format.
> Kris: could you identify which of your package.json fields should be
> in this spec. Some are custom fields for Narwhal, but I'd like to get
> a complete set of fields here. Can you identify any candidates I've
> missed?
Sure.
* maintainer
* directory.jars should be recommended even though it is not
generally applicable
* directory.engines should be in there for any system that has
engine-specific components for one or more engines, including general
engines like "default". We may or may not want to maintain a registry
for engine, os, cpu, and license names. We probably should, as a
freely-editable wiki page; "spidermonkey", "v8", "node", "rhino",
"mozilla", "jsc", "flusspferd", "narwhal", "gpsee". It's like a style
sheet.
* async needs to be there as a recommendation to package maintainers
or users who are trying to maintain the "no-sync" ideology.
On Dec 16, 2:34 pm, Kris Kowal <cowbertvon...@gmail.com> wrote:
> We should have keywords for "package-manager search keyword" commands,
> like "pkgmgr search wiki markup". We might want to go so far as
> having an evolving wiki page to recommend keywords for particular
> types of services.
Agree, that was my intent/understanding of the keywords field. Are you
advocating then to remove categories?
> > Author: being a single field - split it into three (or an array of 3 elements) rather than requiring a fixed format that people will inevitably get wrong (and then only the name of the 3 is required).
> Tusk normalizes author, maintainer, and contributor fields to a {name,
> url, email} hash. A string of comma separated terms might suffice
> with a parser that can distinguish a web page from an email. The
> author hash might be extended with some sort of unique identifier like
> a Github user name for package managers to ensure consistency of
> author fields across packages.
Okay, based on feedback, lets make it a hash of name, email, web. Same
for contributors
> > Dependencies: not sure the version handling is right. if we are using semantic versioning then isn't just [ "ejs", "1.0.0"] enough and implies the >= part and "< 2.0" is implicit from SemVer. (I also don't like '>=' as it implies '=' should work and I really dont want to get into the culture of letting people do that)
> > stability: again, doesn't SemVer cover this and make it redundant?
Okay, lets remove version operators and take a stance with SemVer.
> > directories: purpose? And if its a hash what are the keys?
> This is intended to replace the top-level "lib", "bin", "docs", &c
> properties that Tusk uses. I think it's fine to make a special name
> space for these properties; we're on the verge of name conflicts in
> Tusk. It should be emphasized that these are intended to override
> default locations by the same names, and that an array should be
> provided if there are multiple directories that contain that kind of
> file, like {"directories": {"bin": ["bin", "sbin"]}}.
AGREE. This is optional and only required if you have a non-standard
dir layout.
> > scripts: Hmmm I thought this was going to be list of scripts to install or some such. Perhaps "commands" or "build_commands" is a better name?
> +1 to scripts to forestall bike shedding if possible.
Yippee.
> Let's leave "stability" off. It's purely informational. We can take
> care of "stable", "unstable", and "test" by providing different
> catalogs that offer different versions. If someone wants to volunteer
> what catalog they would like to be included in, we might need to do
> this differently. I had considered possibly advertising a "versions":
> {} property and "trains": {stable, unstable, test, dev} with alternate
> sources. My brain exploded and I had to scale back. Unless someone
> can write a thesis on this issue right now, I think we should table
> it.
Uncle.
> I've regretted using tuples instead of hashes on several occasions. I
> advise the use of Objects for any structural data instead of having
> position imply the label.
Agree.
> > * name - the name of the package. This must be a lowercase alpha-numeric name without spaces. It may include "." or "_" or "-" characters.
> I recommend ditching "_" and ".".
We need "." in ejscript. Please... We could recommend that the names
be camelCase if multi-word instead of "_". But do we really care
here? They are opaque names.
> > * categories - an Array of String keywords to classify the package.
> I think that we should wrap these into keywords and have catalog
> maintainers encourgage consistency here.
Agreed above.
> > * author - Original or primary author of the package. Must be of the format:
> > "Name (URL) <EMAIL>", where (URL) and <EMAIL> are optional but recommended. For
> > example:
> > "Bill Bloggs (http://www.bblogmedia.com) <billbl...@bblogmedia.com)
> I think we should allow this format, comma delimited, and an Object format,
> all of which would get normalized to the Object.
Given the feedback, I'd recommend we make this a hash and not allow
dual formats. {name,email,web}
> > * bugs - URL for submitting bugs. Can be mailto or http.
> I'm thinking we should so something similar to author for this one, where
> "url" and "email" can be specified, comma delimited, or (urled) and <emailed>.
Make sense. How about:
bugs: {
mail: "bugs@acme",
http: "....",
}
> > * license - array of licenses under which the package is provided. Each
> > license is a tuple where the first element is the kind of license and the
> > second element is a URL to the license. For example
> > licenses: [["GPL",
> > "http://www.ejscript.org/products/ejs/doc/licenses/gpl.html"]]
> I'm thinking we should have a standard set of license names, and then allow an
> Object for custom variants with {"name", "url"} objects instead of tuples.
It is a bit of a zoo. I tried this, but there are so many different
licenses.
> > * location - Array of repositories where the package can be located. Each repository is a tuple where the first element is the kind of repository and the second element is a URL path to clone/checkout the package. For example:
> > location: [["mercurial", "http://hg.embedthis.com/ejs"]]
> I think we ought to leave this out for now since it's highly coupled to the
> catalog specification, I think. In my latest work on Tusk, the catalog
> consolidation system automatically adds a "source" property to the package
> descriptor which is the source descriptor that was used to get the rest of the
> information. It has a "type" field and the rest of its properties depend on
> the VCS or whether a VCS was used at all.
I was thinking this is the authoritative source for the package not
necessarily where a catalogue may be proxying it. So I think we should
retain this here. Tusk could still add a source which is where this
particular download came from.
> > * dependencies - Array of prerequisite packages on which this package depends in order to install and run. Each dependency is an array with one to three elements. The first element is the dependent package name and is mandatory. The second is an optional version expression defining the lowest qualifying version. The third element is a version expression defining the highest qualifying version. Version expressions are of the form: operator SPACE version. For example:
> > dependencies: [ "ejs", ">= 1.0.0", "< 2.0"].
> It does need to be an array. For the simple case, I think a mere package name
> should be permitted, and the version "" implied, which should accept anything.
Agreed.
> For the complex case, it should be an Object with something like {name,
> version} or {name, min, max} if you think that's critical.
I might wait for more input on whether this should be a tuple or hash.
I can see your point.
> > * conforms - Array of relevant CommonJS specifications this package supports. TBD: define these specifiers. For example:
> > conforms: [ "CommonJS-Modules-1.0", "CommonJS-JSGI-1.0"]
> I recommend "implements" and that the value be a URI of the specification,
> perhaps identical to its URL. Perhaps alternately its Wiki page name in case
> we move.
Better.
> > Package managers and loaders should ignore unknown fields in the package descriptor file.
> If we make this a normative clause, we should aggressively reserve any words we ...
> > Can you identify any candidates I've
> > missed?
> * maintainer
Is this the point contributor to receive issue requests? Can you
elaborate on the purpose. I tried to cut down to author and
contributors. Can we refactor these to only have 2 fields for these.
ie. pick 2 from (author, contributors, maintainer). Or refactor in
some way to have two instead of three.
> * directory.jars should be recommended even though it is not
> generally applicable
I think this is an example of a collection of things which are not
required, but if present should adopt this form. I'll create a section
for these.
> * directory.engines should be in there for any system that has
> engine-specific components for one or more engines, including general
> engines like "default". We may or may not want to maintain a registry
> for engine, os, cpu, and license names. We probably should, as a
> freely-editable wiki page; "spidermonkey", "v8", "node", "rhino",
> "mozilla", "jsc", "flusspferd", "narwhal", "gpsee". It's like a style
> sheet.
Yes, this is just the same as os and cpu. I'll create a list of
approved names to the proposal.
> * async needs to be there as a recommendation to package maintainers
> or users who are trying to maintain the "no-sync" ideology.
This doesn't quite feel right. I know the need, but there will always
be a long list of things like this. Surely this is the same as
"stability" and the answers are the same. ie. we may need an async-
only catalog.
On Wed, Dec 16, 2009 at 6:06 PM, mob <m...@embedthis.com> wrote:
> > > Can you identify any candidates I've
> > > missed?
> > * maintainer
> Is this the point contributor to receive issue requests? Can you
> elaborate on the purpose. I tried to cut down to author and
> contributors. Can we refactor these to only have 2 fields for these.
> ie. pick 2 from (author, contributors, maintainer). Or refactor in
> some way to have two instead of three.
> > * directory.jars should be recommended even though it is not
> > generally applicable
> I think this is an example of a collection of things which are not
> required, but if present should adopt this form. I'll create a section
> for these.
> > * directory.engines should be in there for any system that has
> > engine-specific components for one or more engines, including general
> > engines like "default". We may or may not want to maintain a registry
> > for engine, os, cpu, and license names. We probably should, as a
> > freely-editable wiki page; "spidermonkey", "v8", "node", "rhino",
> > "mozilla", "jsc", "flusspferd", "narwhal", "gpsee". It's like a style
> > sheet.
> Yes, this is just the same as os and cpu. I'll create a list of
> approved names to the proposal.
> > * async needs to be there as a recommendation to package maintainers
> > or users who are trying to maintain the "no-sync" ideology.
> This doesn't quite feel right. I know the need, but there will always
> be a long list of things like this. Surely this is the same as
> "stability" and the answers are the same. ie. we may need an async-
> only catalog.
[Two replies merged into one here]
On 16 Dec 2009, at 23:06, mob wrote:
>>> Can you identify any candidates I've missed?
>> * maintainer
> Is this the point contributor to receive issue requests? Can you
> elaborate on the purpose. I tried to cut down to author and
> contributors. Can we refactor these to only have 2 fields for these.
> ie. pick 2 from (author, contributors, maintainer). Or refactor in
> some way to have two instead of three.
Is author relevant at the package.json level, or is that just something that is better in the package/module's documentation?
>> * directory.jars should be recommended even though it is not
>> generally applicable
> I think this is an example of a collection of things which are not
> required, but if present should adopt this form. I'll create a section
> for these.
>> * directory.engines should be in there for any system that has
>> engine-specific components for one or more engines, including general
>> engines like "default". We may or may not want to maintain a registry
>> for engine, os, cpu, and license names. We probably should, as a
>> freely-editable wiki page; "spidermonkey", "v8", "node", "rhino",
>> "mozilla", "jsc", "flusspferd", "narwhal", "gpsee". It's like a style
>> sheet.
> Yes, this is just the same as os and cpu. I'll create a list of
> approved names to the proposal.
As a corollary to this how do you signal that "this package only works on engine Y"?
>> * async needs to be there as a recommendation to package maintainers
>> or users who are trying to maintain the "no-sync" ideology.
> This doesn't quite feel right. I know the need, but there will always
> be a long list of things like this. Surely this is the same as
> "stability" and the answers are the same. ie. we may need an async-
> only catalog.
Or this is a keyword/category? (as dean said while I was composing this)
On 16 Dec 2009, at 22:52, mob wrote:
> On Dec 16, 2:34 pm, Kris Kowal <cowbertvon...@gmail.com> wrote:
>> We should have keywords for "package-manager search keyword" commands,
>> like "pkgmgr search wiki markup". We might want to go so far as
>> having an evolving wiki page to recommend keywords for particular
>> types of services.
> Agree, that was my intent/understanding of the keywords field. Are you
> advocating then to remove categories?
Unless we enumerate the values for one of these they are both just free-form inputs. So I think we either need to enumerate one and have the other as freeform, or remove one of them and have the remaining as 'free form'.
>>> Dependencies: not sure the version handling is right. if we are using semantic versioning then isn't just [ "ejs", "1.0.0"] enough and implies the >= part and "< 2.0" is implicit from SemVer. (I also don't like '>=' as it implies '=' should work and I really dont want to get into the culture of letting people do that)
>>> stability: again, doesn't SemVer cover this and make it redundant?
> Okay, lets remove version operators and take a stance with SemVer.
Going with just a single version (impliying v2 is not compatible with v1, correct?)
>>> scripts: Hmmm I thought this was going to be list of scripts to install or some such. Perhaps "commands" or "build_commands" is a better name?
>> +1 to scripts to forestall bike shedding if possible.
> Yippee.
Good point: name is fine as it is. Is there a known/define set of keys on scripts? Just the 4 listed?
>>> * name - the name of the package. This must be a lowercase alpha-numeric name without spaces. It may include "." or "_" or "-" characters.
>> I recommend ditching "_" and ".".
> We need "." in ejscript. Please... We could recommend that the names
> be camelCase if multi-word instead of "_". But do we really care
> here? They are opaque names.
Agreed - name should be as unrestricted in this spec as possible. Why arbitrarily limit it? (in particular why no uppercase chars?)
>>> * bugs - URL for submitting bugs. Can be mailto or http.
>> I'm thinking we should so something similar to author for this one, where
>> "url" and "email" can be specified, comma delimited, or (urled) and <emailed>.
Sounds good. Optionally allow just a simple string where in it looks for "@" as an email, or else treats as a URL (this might be more complex than is needed)?
>>> * license - array of licenses under which the package is provided. Each
>>> license is a tuple where the first element is the kind of license and the
>>> second element is a URL to the license. For example
>>> licenses: [["GPL",
>>> "http://www.ejscript.org/products/ejs/doc/licenses/gpl.html"]]
>> I'm thinking we should have a standard set of license names, and then allow an
>> Object for custom variants with {"name", "url"} objects instead of tuples.
> It is a bit of a zoo. I tried this, but there are so many different
> licenses.
Licenses are a bit of a zoo, but there are some common ones: GPLv2, GPLv3, LGPL, MIT, BSD, Apache, Mozilla would be the most common, and anything not in that list needs {"name": "url"}
>>> * location - Array of repositories where the package can be located. Each repository is a tuple where the first element is the kind of repository and the second element is a URL path to clone/checkout the package. For example:
>>> location: [["mercurial", "http://hg.embedthis.com/ejs"]]
>> I think we ought to leave this out for now since it's highly coupled to the
>> catalog specification, I think. In my latest work on Tusk, the catalog
>> consolidation system automatically adds a "source" property to the package
>> descriptor which is the source descriptor that was used to get the rest of the
>> information. It has a "type" field and the rest of its properties depend on
>> the VCS or whether a VCS was used at all.
> I was thinking this is the authoritative source for the package not
> necessarily where a catalogue may be proxying it. So I think we should
> retain this here. Tusk could still add a source which is where this
> particular download came from.
So the package.json should include VCS repository locations, but yeah, maybe not the location where you can get releases from.
>>> * dependencies - Array of prerequisite packages on which this package depends in order to install and run. Each dependency is an array with one to three elements. The first element is the dependent package name and is mandatory. The second is an optional version expression defining the lowest qualifying version. The third element is a version expression defining the highest qualifying version. Version expressions are of the form: operator SPACE version. For example:
>>> dependencies: [ "ejs", ">= 1.0.0", "< 2.0"].
>> It does need to be an array. For the simple case, I think a mere package name
>> should be permitted, and the version "" implied, which should accept anything.
> Agreed.
>> For the complex case, it should be an Object with something like {name,
>> version} or {name, min, max} if you think that's critical.
> I might wait for more input on whether this should be a tuple or hash.
> I can see your point.
I'd vote for not allowing complex cases :) This is what SemVer is supposed to handle (at least by my reading of it).
So ideally I'd like some way of signalling a dependancy on 'external libraries or programs' (such as libmysql or a particular build system). The package management tools might not be able to provide/fulfil this dependancy in all cases (or even in most cases) but they could at least signal to the user or allow it to be displayed in a nice format.
> [Two replies merged into one here]
> On 16 Dec 2009, at 23:06, mob wrote:
> Can you identify any candidates I've missed?
> * maintainer
> Is this the point contributor to receive issue requests? Can you
> elaborate on the purpose. I tried to cut down to author and
> contributors. Can we refactor these to only have 2 fields for these.
> ie. pick 2 from (author, contributors, maintainer). Or refactor in
> some way to have two instead of three.
> Is author relevant at the package.json level, or is that just something
> that is better in the package/module's documentation?
> * directory.jars should be recommended even though it is not
> generally applicable
> I think this is an example of a collection of things which are not
> required, but if present should adopt this form. I'll create a section
> for these.
> * directory.engines should be in there for any system that has
> engine-specific components for one or more engines, including general
> engines like "default". We may or may not want to maintain a registry
> for engine, os, cpu, and license names. We probably should, as a
> freely-editable wiki page; "spidermonkey", "v8", "node", "rhino",
> "mozilla", "jsc", "flusspferd", "narwhal", "gpsee". It's like a style
> sheet.
> Yes, this is just the same as os and cpu. I'll create a list of
> approved names to the proposal.
> As a corollary to this how do you signal that "this package only works on
> engine Y"?
> * async needs to be there as a recommendation to package maintainers
> or users who are trying to maintain the "no-sync" ideology.
> This doesn't quite feel right. I know the need, but there will always
> be a long list of things like this. Surely this is the same as
> "stability" and the answers are the same. ie. we may need an async-
> only catalog.
> Or this is a keyword/category? (as dean said while I was composing this)
> On 16 Dec 2009, at 22:52, mob wrote:
> On Dec 16, 2:34 pm, Kris Kowal <cowbertvon...@gmail.com> wrote:
> We should have keywords for "package-manager search keyword" commands,
> like "pkgmgr search wiki markup". We might want to go so far as
> having an evolving wiki page to recommend keywords for particular
> types of services.
> Agree, that was my intent/understanding of the keywords field. Are you
> advocating then to remove categories?
> Unless we enumerate the values for one of these they are both just
> free-form inputs. So I think we either need to enumerate one and have the
> other as freeform, or remove one of them and have the remaining as 'free
> form'.
> Dependencies: not sure the version handling is right. if we are using
> semantic versioning then isn't just [ "ejs", "1.0.0"] enough and implies the
> >= part and "< 2.0" is implicit from SemVer. (I also don't like '>=' as it
> implies '=' should work and I really dont want to get into the culture of
> letting people do that)
> stability: again, doesn't SemVer cover this and make it redundant?
> Okay, lets remove version operators and take a stance with SemVer.
> Going with just a single version (impliying v2 is not compatible with v1,
> correct?)
> scripts: Hmmm I thought this was going to be list of scripts to install or
> some such. Perhaps "commands" or "build_commands" is a better name?
> +1 to scripts to forestall bike shedding if possible.
> Yippee.
> Good point: name is fine as it is. Is there a known/define set of keys on
> scripts? Just the 4 listed?
> * name - the name of the package. This must be a lowercase alpha-numeric
> name without spaces. It may include "." or "_" or "-" characters.
> I recommend ditching "_" and ".".
> We need "." in ejscript. Please... We could recommend that the names
> be camelCase if multi-word instead of "_". But do we really care
> here? They are opaque names.
> Agreed - name should be as unrestricted in this spec as possible. Why
> arbitrarily limit it? (in particular why no uppercase chars?)
> Sounds good. Optionally allow just a simple string where in it looks for
> "@" as an email, or else treats as a URL (this might be more complex than is
> needed)?
> * license - array of licenses under which the package is provided. Each
> license is a tuple where the first element is the kind of license and the
> second element is a URL to the license. For example
> I'm thinking we should have a standard set of license names, and then allow
> an
> Object for custom variants with {"name", "url"} objects instead of tuples.
> It is a bit of a zoo. I tried this, but there are so many different
> licenses.
> Licenses are a bit of a zoo, but there are some common ones: GPLv2, GPLv3,
> LGPL, MIT, BSD, Apache, Mozilla would be the most common, and anything not
> in that list needs {"name": "url"}
And as Kris pointed out, we could keep an authoritative json map (perhaps
built from some wiki page) to extend this. This is actually something the
internets need in general and perhaps could eventually be administered by a
group outside of CommonJS.
> * location - Array of repositories where the package can be located. Each
> repository is a tuple where the first element is the kind of repository and
> the second element is a URL path to clone/checkout the package. For example:
> I think we ought to leave this out for now since it's highly coupled to the
> catalog specification, I think. In my latest work on Tusk, the catalog
> consolidation system automatically adds a "source" property to the package
> descriptor which is the source descriptor that was used to get the rest of
> the
> information. It has a "type" field and the rest of its properties depend
> on
> the VCS or whether a VCS was used at all.
> I was thinking this is the authoritative source for the package not
> necessarily where a catalogue may be proxying it. So I think we should
> retain this here. Tusk could still add a source which is where this
> particular download came from.
> So the package.json should include VCS repository locations, but yeah,
> maybe not the location where you can get releases from.
> * dependencies - Array of prerequisite packages on which this package
> depends in order to install and run. Each dependency is an array with one to
> three elements. The first element is the dependent package name and is
> mandatory. The second is an optional version expression defining the lowest
> qualifying version. The third element is a version expression defining the
> highest qualifying version. Version expressions are of the form: operator
> SPACE version. For example:
> dependencies: [ "ejs", ">= 1.0.0", "< 2.0"].
> It does need to be an array. For the simple case, I think a mere package
> name
> should be permitted, and the version "" implied, which should accept
> anything.
> Agreed.
> For the complex case, it should be an Object with something like {name,
> version} or {name, min, max} if you think that's critical.
> I might wait for more input on whether this should be a tuple or hash.
> I can see your point.
> I'd vote for not allowing complex cases :) This is what SemVer is supposed
> to handle (at least by my reading of it).
> Wheeeee long!
> -ash
> --
> You received this message because you are subscribed to the Google Groups
> "CommonJS" group.
> To post to this group, send email to commonjs@googlegroups.com.
> To unsubscribe from this group, send email to
> commonjs+unsubscribe@googlegroups.com<commonjs%2Bunsubscribe@googlegroups.c om>
> .
> For more options, visit this group at
> http://groups.google.com/group/commonjs?hl=en.
> >> * maintainer > > Is this the point contributor to receive issue requests? Can you > > elaborate on the purpose. I tried to cut down to author and > > contributors. Can we refactor these to only have 2 fields for these. > > ie. pick 2 from (author, contributors, maintainer). Or refactor in > > some way to have two instead of three.
> Is author relevant at the package.json level, or is that just something that is better in the package/module's documentation?
Could be right. The original author is not nearly as relevant as the current maintainer. How about we use those 2: maintainer and contributors. The author could be the first contributor by convention?
> As a corollary to this how do you signal that "this package only works on engine Y"?
Create a psudo package for the engine and depend on it.
For ejscript, we will have a package for each key component of the platform.
> Or this is a keyword/category? (as dean said while I was composing this)
Agree.
> Unless we enumerate the values for one of these they are both just free-form inputs. So I think we either need to enumerate one and have the other as freeform, or remove one of them and have the remaining as 'free form'.
I'm now leaning this way. Suggest we remove categories and just have keywords. Simpler and then the package tools can take over from there.
> >>> Dependencies: not sure the version handling is right. if we are using semantic versioning then isn't just [ "ejs", "1.0.0"] enough and implies the >= part and "< 2.0" is implicit from SemVer. (I also don't like '>=' as it implies '=' should work and I really dont want to get into the culture of letting people do that) > >>> stability: again, doesn't SemVer cover this and make it redundant?
> > Okay, lets remove version operators and take a stance with SemVer.
> Going with just a single version (impliying v2 is not compatible with v1, correct?)
We have a choice with that. One version could mean: - That version or later - That major version only.
I'm leaning toward the former. If someone says "package", "1.2.3". What they really mean is 1.2.3 or later. If you want it to mean only version 1, you would say
"package", "1", "2"
> >>> scripts: Hmmm I thought this was going to be list of scripts to install or some such. Perhaps "commands" or "build_commands" is a better name? > >> +1 to scripts to forestall bike shedding if possible. > Good point: name is fine as it is. Is there a known/define set of keys on scripts? Just the 4 listed?
I think this will grow from experience. We use install, uninstall and build. But other platforms may need others. Perhaps "test"?
> Sounds good. Optionally allow just a simple string where in it looks for "@" as an email, or else treats as a URL (this might be more complex than is needed)?
I think so, I'd avocate that we don't allow such simplifications. The above is very clear and it just makes parsers and tools harder to write and maintain.
> >>> * license - array of licenses under which the package is provided. Each > >>> license is a tuple where the first element is the kind of license and the > >>> second element is a URL to the license. For example > >>> licenses: [["GPL", > >>> "http://www.ejscript.org/products/ejs/doc/licenses/gpl.html"]]
> >> I'm thinking we should have a standard set of license names, and then allow an > >> Object for custom variants with {"name", "url"} objects instead of tuples.
> > It is a bit of a zoo. I tried this, but there are so many different > > licenses.
> Licenses are a bit of a zoo, but there are some common ones: GPLv2, GPLv3, LGPL, MIT, BSD, Apache, Mozilla would be the most common, and anything not in that list needs {"name": "url"}
Ash Berlin wrote: > [Two replies merged into one here] > On 16 Dec 2009, at 23:06, mob wrote: >>>> * location - Array of repositories where the package can be located. >>>> Each repository is a tuple where the first element is the kind of >>>> repository and the second element is a URL path to clone/checkout >>>> the package. For example: >>>> location: [["mercurial", "http://hg.embedthis.com/ejs"]]
>> I was thinking this is the authoritative source for the package not >> necessarily where a catalogue may be proxying it. So I think we should >> retain this here. Tusk could still add a source which is where this >> particular download came from.
> So the package.json should include VCS repository locations, but yeah, > maybe not the location where you can get releases from.
+1 I think it is essential to be able to easily find the original source of a package to encourage collaboration no matter how it was distributed.
If bug reports always target the original source it may make sense to combine "bugs" and "location".
>> * version - a version string conforming to the Semantic Versioning > requirements (http://semver.org/)
As for versioning and stability. Being able to declare a 2.X release as alpha or beta is important I think until it becomes stable. Can we extend the Semantic Versioning with this:
mob wrote: >>>>> scripts: Hmmm I thought this was going to be list of scripts to install or some such. Perhaps "commands" or "build_commands" is a better name? >>>> +1 to scripts to forestall bike shedding if possible. >> Good point: name is fine as it is. Is there a known/define set of keys on scripts? Just the 4 listed?
> I think this will grow from experience. We use install, uninstall and > build. But other platforms may need others. Perhaps "test"?
>> So the package.json should include VCS repository locations, but yeah, >> maybe not the location where you can get releases from.
> +1 I think it is essential to be able to easily find the original source > of a package to encourage collaboration no matter how it was distributed.
> If bug reports always target the original source it may make sense to > combine "bugs" and "location".
Hmmm yes that could work.
>>> * version - a version string conforming to the Semantic Versioning >> requirements (http://semver.org/)
> As for versioning and stability. Being able to declare a 2.X release as > alpha or beta is important I think until it becomes stable. Can we > extend the Semantic Versioning with this:
Or there is the .deb form of 2.0~1 (which is < 2.0 iirc.) In general I think a way of putting developer/preview versions up for explicit download is a good thing (so long as they need to be explicitly required, and by default the package installer only looks for normal versions).
christoph...@christophdorn.com> wrote: > Ash Berlin wrote: > > [Two replies merged into one here] > > On 16 Dec 2009, at 23:06, mob wrote: > >>>> * location - Array of repositories where the package can be located. > >>>> Each repository is a tuple where the first element is the kind of > >>>> repository and the second element is a URL path to clone/checkout > >>>> the package. For example: > >>>> location: [["mercurial", "http://hg.embedthis.com/ejs"]]
> >> I was thinking this is the authoritative source for the package not > >> necessarily where a catalogue may be proxying it. So I think we should > >> retain this here. Tusk could still add a source which is where this > >> particular download came from.
> > So the package.json should include VCS repository locations, but yeah, > > maybe not the location where you can get releases from.
> +1 I think it is essential to be able to easily find the original source > of a package to encourage collaboration no matter how it was distributed.
> If bug reports always target the original source it may make sense to > combine "bugs" and "location".
> >> * version - a version string conforming to the Semantic Versioning > > requirements (http://semver.org/)
> As for versioning and stability. Being able to declare a 2.X release as > alpha or beta is important I think until it becomes stable. Can we > extend the Semantic Versioning with this:
SemVer is one day old and we're already talking about extending it...heh...
But this *is* relevant version info and I can't see how (after 1.0.0) it's possible to express this. Not being able to cut a beta release package would be pretty constraining, especially for slow-moving projects. One comparatively easy way to extend SemVer is to allow letters and specify the sort as letters < numbers. Then you could have 2.a.1, 2.a.2, 2.b.1, 2.0.0, etc... You could also have use this to create a train for minor releases (2.2.a, 2.2.b, 2.2.c... all sorting before 2.2.0). Dependencies would never resolve to an *extended* SemVar because they're technically invalid and thus unstable.
On Wed, Dec 16, 2009 at 3:40 PM, mob <m...@embedthis.com> wrote: > I'm leaning toward the former. If someone says "package", "1.2.3". > What they really mean is 1.2.3 or later.
Actually, if they say "1.2", they mean greater or equal to "1.2.0" but less than "2". Major versions introduce changes that require code changes. Minor versions introduce changes that are strictly backward compatible. Patch versions are backward and forward compatible and the most recent is always the best choice. I think all the major cases are covered.
