Packages 1.1 version range definitions

152 views
Skip to first unread message

Mikeal Rogers

unread,
Mar 24, 2010, 6:46:01 PM3/24/10
to comm...@googlegroups.com
For dependency definitions it is often necessary to declare explicit version requirements. The current semantics are unclear but the proposals for Packages/1.1 are as follows:

1) Strict semver

This proposal requires that all version definitions follow the strictest semver meanings. 1.2.0 would mean that 1.2.0 = 1.2.9.9 are all acceptable versions of the required package. This proposal does not allow for version "locking" at any level higher than 1.2.x.

2) Loose semver

This proposal states that a definition of 1.2 would mean 1.2.0 - 1.2.9 are acceptable and that a definition of 1.2.3 would mean a version "lock" on 1.2.3.

3) Explicit range definitions

This proposal does not use semver to define it's acceptable ranges. Instead, new operators would be defined for use in the version string ("=", ">=", "<=", ">", "<"). This proposal allows for a wider range of definitions but puts a greater burden on package manager implementers and does not encourage semver best practices for package authors.

And that's about where we are. Each proposal has it's merits.

Another version related issue is that the engine keywords currently do not support version definitions. Thoughts?

-Mikeal

Charles Jolley

unread,
Mar 24, 2010, 6:56:30 PM3/24/10
to comm...@googlegroups.com
This is not what the semver spec calls for:

> 1) Strict semver
>
> This proposal requires that all version definitions follow the strictest semver meanings. 1.2.0 would mean that 1.2.0 = 1.2.9.9 are all acceptable versions of the required package. This proposal does not allow for version "locking" at any level higher than 1.2.x.

"1.2.0" should mean that all versions >= 1.2.0 and < 2.0.0 are acceptable. Major version number changes are supposed to indicate backward incompatible changes. All minor versions should indicate new features that are backwards compatible. Patch numbers indicate no feature changes - only bug fixes.

I believe in this case any versions that lack minor version or patch numbers would normalize to their "0" release. i.e. "1.2" would normalize to "1.2.0"



> 2) Loose semver
>
> This proposal states that a definition of 1.2 would mean 1.2.0 - 1.2.9 are acceptable and that a definition of 1.2.3 would mean a version "lock" on 1.2.3.

This would not work since you don't usually want to state that "any version of 1.2 is OK". For example, 1.2.0 might have a critical bug while 1.2.1 fixes it. You need a way to state that any version > 1.2.1 is OK.

Additionally, version numbers can be greater than "9". For example, 1.2.100 is a valid version as is 1.33.200

> 3) Explicit range definitions
>
> This proposal does not use semver to define it's acceptable ranges. Instead, new operators would be defined for use in the version string ("=", ">=", "<=", ">", "<"). This proposal allows for a wider range of definitions but puts a greater burden on package manager implementers and does not encourage semver best practices for package authors.

I would propose a fourth options:

4. Explicit Range Definitions with the "compatible" operator

This works just like #3 above with an added operator ('~=' ?) that means "semver compatible". This could be the default if you do not specify a version.

e.g simply stating: "1.2.0" or "1.2" (which normalizes to "1.2.0") would be the same as "~ 1.2.0" which means "any version >= 1.2.0 but less than 2.0.0" according to the semver spec

Ash Berlin

unread,
Mar 24, 2010, 7:32:56 PM3/24/10
to comm...@googlegroups.com


I was hinting at 1+3. If you provide just a single number with no range/operator, then you get strict sem-ver-nes. If you provide any kind of range or rel operator then you get exactly what you asked for.

Tho i could go for Charles' "~" operator if other people also like it

-ash

Mikeal Rogers

unread,
Mar 24, 2010, 7:38:28 PM3/24/10
to comm...@googlegroups.com
On Wed, Mar 24, 2010 at 3:56 PM, Charles Jolley <cha...@sproutit.com> wrote:
This is not what the semver spec calls for:

> 1) Strict semver
>
> This proposal requires that all version definitions follow the strictest semver meanings. 1.2.0 would mean that 1.2.0 = 1.2.9.9 are all acceptable versions of the required package. This proposal does not allow for version "locking" at any level higher than 1.2.x.

"1.2.0" should mean that all versions >= 1.2.0 and < 2.0.0 are acceptable.  Major version number changes are supposed to indicate backward incompatible changes.  All minor versions should indicate new features that are backwards compatible.  Patch numbers indicate no feature changes - only bug fixes.

Except for the gigantic pre-1.0 loophole. From semver.org:

  1. Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Unfortunately, nearly every javascript package I'm using right now pre-1.0 which means if i want to depend on it I have no way to specify version targeting or locking.

-Mikeal

Charles Jolley

unread,
Mar 24, 2010, 7:45:33 PM3/24/10
to comm...@googlegroups.com
How about a 5th option:

- "1.2.0" (or maybe "~1.2.0") means semver compatible.  i.e. allow anything >= 1.2.0 and < 2.0.0
- "=1.2.0" means strict compatible. i.e. allow only "1.2.0" exactly

I wonder if this would cover almost all of the proper use cases.  Post 1.0.0 packages you should usually use the first option.  Pre 1.0.0 packages you should use the second option (since anything can change at any time - upgrades or downgrades are never safe).

Most other uses (like ">=") I've seen end in tears anyway and checking the first character is simple.

--
You received this message because you are subscribed to the Google Groups "CommonJS" group.
To post to this group, send email to comm...@googlegroups.com.
To unsubscribe from this group, send email to commonjs+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/commonjs?hl=en.

Christoph Dorn

unread,
Mar 24, 2010, 7:54:22 PM3/24/10
to comm...@googlegroups.com
Charles Jolley wrote:
> How about a 5th option:
>
> - "1.2.0" (or maybe "~1.2.0") means semver compatible. i.e. allow
> anything >= 1.2.0 and < 2.0.0
> - "=1.2.0" means strict compatible. i.e. allow only "1.2.0" exactly
>
> I wonder if this would cover almost all of the proper use cases. Post
> 1.0.0 packages you should usually use the first option. Pre 1.0.0
> packages you should use the second option (since anything can change at
> any time - upgrades or downgrades are never safe).


I would rather specify that minor version can break backwards
compatibility and patch version cannot for < 1.

In what cases do you need to specify an exact version and how does it
work with other packages specifying the same dependency with a
different version?

Christoph


>
> Most other uses (like ">=") I've seen end in tears anyway and checking
> the first character is simple.
>
> On Mar 24, 2010, at 4:38 PM, Mikeal Rogers wrote:
>
>>
>>
>> On Wed, Mar 24, 2010 at 3:56 PM, Charles Jolley <cha...@sproutit.com
>> <mailto:cha...@sproutit.com>> wrote:
>>
>> This is not what the semver spec calls for:
>>
>> > 1) Strict semver
>> >
>> > This proposal requires that all version definitions follow the
>> strictest semver meanings. 1.2.0 would mean that 1.2.0 = 1.2.9.9
>> are all acceptable versions of the required package. This proposal
>> does not allow for version "locking" at any level higher than 1.2.x.
>>
>> "1.2.0" should mean that all versions >= 1.2.0 and < 2.0.0 are
>> acceptable. Major version number changes are supposed to indicate
>> backward incompatible changes. All minor versions should indicate
>> new features that are backwards compatible. Patch numbers
>> indicate no feature changes - only bug fixes.
>>
>>
>> Except for the gigantic pre-1.0 loophole. From semver.org

>> <http://semver.org/>:
>>
>> 1.


>>
>> Major version zero (0.y.z) is for initial development. Anything
>> may change at any time. The public API should not be considered
>> stable.
>>
>> Unfortunately, nearly every javascript package I'm using right now
>> pre-1.0 which means if i want to depend on it I have no way to specify
>> version targeting or locking.
>>
>> -Mikeal
>>
>> --
>> You received this message because you are subscribed to the Google
>> Groups "CommonJS" group.
>> To post to this group, send email to comm...@googlegroups.com

>> <mailto:comm...@googlegroups.com>.


>> To unsubscribe from this group, send email to
>> commonjs+u...@googlegroups.com

>> <mailto:commonjs+u...@googlegroups.com>.

Kris Kowal

unread,
Mar 24, 2010, 7:54:38 PM3/24/10
to comm...@googlegroups.com
On Wed, Mar 24, 2010 at 4:45 PM, Charles Jolley <cha...@sproutit.com> wrote:
> How about a 5th option:
> - "1.2.0" (or maybe "~1.2.0") means semver compatible.  i.e. allow anything
>>= 1.2.0 and < 2.0.0
> - "=1.2.0" means strict compatible. i.e. allow only "1.2.0" exactly
> I wonder if this would cover almost all of the proper use cases.  Post 1.0.0
> packages you should usually use the first option.  Pre 1.0.0 packages you
> should use the second option (since anything can change at any time -
> upgrades or downgrades are never safe).
> Most other uses (like ">=") I've seen end in tears anyway and checking the
> first character is simple.

Great idea.

Kris Kowal

Charles Jolley

unread,
Mar 24, 2010, 8:04:52 PM3/24/10
to comm...@googlegroups.com
> I would rather specify that minor version can break backwards compatibility and patch version cannot for < 1.
>
> In what cases do you need to specify an exact version and how does it work with other packages specifying the same dependency with a different version?

Two cases I can think of:

1. Whenever I want to deploy code to a production, usually I want to lock to the specific version I tested with. I don't want to allow unexpected gotchas to sneak in.

2. < 1.0.0 semver states specifically that all bets are off wrt to changes from one version to the next. In this case, no version change is safe so I would probably want to lock to a specific version and move up only when I want.

Mikeal Rogers

unread,
Mar 25, 2010, 3:20:54 PM3/25/10
to comm...@googlegroups.com
I think we're getting in to the realm of preferences over use cases.

- What would most developers "expect" a version declaration of 1.2.3 to mean?
- What is the behavior most developers would like to have with a version 1.2.3 declaration assuming most packages use proper semver?
- What are the most important edge cases that strictly using semver neglects?

Charles' use case is a very valid one and I think at the very least we need to have semver + '=1.2.3' so that we have a way to version lock when someone explicitly calls it out.

It's my opinion that the current semver semantics where a version declaration of 1.2.3 means any version higher than 1.2.3 but lower than 2.0.0 is not what developers expect but in most cases what they would prefer given most packages stick with semver conventions.

-Mikeal
Reply all
Reply to author
Forward
0 new messages