implement extended syntax for package version ranges #225

Closed
bos opened this Issue May 24, 2012 · 4 comments

Projects

None yet

2 participants

@bos
Contributor
bos commented May 24, 2012

(Imported from Trac #232, reported by @dcoutts on 2008-02-05)

Revised proposal: http://www.haskell.org/pipermail/cabal-devel/2008-January/001786.html

Reproduced here:

In order to make it easy for package package authors to describe correct and robust dependencies we (Duncan Coutts and I) propose the following syntactical extension to version range specifications in package files.

Wildcards

  ~ 1.2.\*  ~~>  >= 1.2 && < 1.3
in general
  ~ x.y.\*   ~~>   >= x.y && < x.(y+1)
The "~" operator should be read as "in the range of". Another option would have been "-", but this is used to specify exact versions in other parts of the Cabal infrastructure , e.g., "cabal install xmonad-0.5".

This is the most common specification of package dependencies. The assumption is that changes in the last version number indicate only backwards compatible changes, as is suggested in the new package versioning policy [1]. The use of "*" matches the common usage as a wildcard character.

Upward Ranges

 ~ 1.2.1+  ~~>  >= 1.2.1 && < 1.3
in general
 ~ x.y.z+  ~~>  >= x.y.z && < x.(y+1)
The idea here is that sometimes packages need a certain patch level or, as in Cabal's case, a stable release and possible further bugfixes. In those cases the wildcard notation is too liberal, however the explicit range description would be too noisy (and possibly error prone). (Also, using "+" instead of "*" serves as better visual distinction.)
@nominolo nominolo was assigned May 24, 2012
Contributor
bos commented May 24, 2012

(Imported comment by @dcoutts on 2008-02-05)

Note that if the foo ~ 1.2.1+ syntax is too confusing we could do with just foo ~ 1.2.* && >= 1.2.1. It also allows to depend on a micro release that fixes a bug like foo ~ 1.2.* && >= 1.2.0.1.

Contributor
bos commented May 24, 2012

(Imported comment by @dcoutts on 2008-05-04)

Added the wildcard syntax but not the upward range syntax.

Thu Jun 19 18:50:06 BST 2008  Duncan Coutts <duncan@haskell.org>
- Add version wildcard syntax
  build-depends: foo ~1.2.*
  means:
    build-depends: foo >=1.2 && <1.3
  It's also valid everywhere else version ranges are used.
  
I think it might be best to stick with that and not implement the upward range syntax. The few people I showed both syntaxes to were able to guess the meaning of the wildcard syntax but not the upward range syntax.

So if we're happy then we should document the syntax in the user guide and close the ticket.

Note that if we add this to the Cabal-1.4 branch (which is possible since it does not change any types) then we need to not let it be used in packages uploaded to hackage yet.

Contributor
bos commented May 24, 2012

(Imported comment by @nominolo on 2008-06-19)

It is indeed confusing, 1.2.3+ looks all too much like >= 1.2.3. Let's drop it then.

Contributor
bos commented May 24, 2012

(Imported comment by @dcoutts on 2008-06-20)

Changed syntax slightly:

Tue Jul 29 16:16:12 BST 2008  Duncan Coutts <duncan@haskell.org>
  * Use "pkg == 1.2.*" as the version wildcard syntax
  Rather than "pkg ~ 1.2.*". This seemed to be the consensus.
  The syntax "pkg == 1.2.*" means "pkg >= 1.2 && < 1.3" and it
  is to encourage people to put upper bounds on api versions.
And now documented too.
Tue Jul 29 17:20:24 BST 2008  Duncan Coutts <duncan@haskell.org>
  * Move docs for build-depends into the build information section
  Since it is shared between libs and exes. Extend the documentation
  to describe the syntax of version constraints, including the new
  version range syntax "build-depends: foo ==1.2.*".
@bos bos closed this May 24, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment