The last sentence of the first paragraph you quoted starts with "A version is intended," but I don't know for sure if it is a complete answer. You'll also notice on the catalog that there are version exceptions, but you may have already read that by now.
https://docs.racket-lang.org/pkg/getting-started.html?q=version%20exceptions#%28part._.Version_.Exceptions%29 Beyond what the manual says, the version field really doesn't mean much in the sense I think you're hinting at. There is no query language where you can ask for, say, the latest version within those available within 4.2.x, for example. Even if there was, it wouldn't be that useful since the default catalog does not maintain artifacts (Bogdan's racksnaps improves on this situation). Also remember that it is the collection, not the package, is the real "unit of exchange" in the Racket ecosystem. If you release a version 2.0 that includes a breaking change in a `foo` collection, it will conflict with any version of any package published by anyone that happens to define modules of the same name in the same collection. There are reasons for this, but that's out of the scope for your question. On 3/16/21 6:51 PM, Jeff Henrikson wrote: > Hello racket-users, > > As far as I can tell from reading the Racket documentation, the racket > package manager has only one field to indicate version. I am trying to > understand the intended use of the version field. > > Here the documentation seems to recommend that packages use the version field > to denote a semantic versioning scheme of for the specific package's release > cycle: > >> https://docs.racket-lang.org/pkg/Package_Concepts.html >> a version — a string of the form ‹maj›.‹min›, ‹maj›.‹min›.‹sub›, or >> ‹maj›.‹min›.‹sub›.‹rel›, where ‹maj›, ‹min›, ‹sub›, and ‹rel› are all >> canonical decimal representations of natural numbers, ‹rel› is not 0, ‹sub› >> is not 0 unless ‹rel› is supplied, ‹min› has no more than two digits, and >> ‹sub› and ‹rel› have no more than three digits. A version is intended to >> reflect available features of a package, and should not be confused with >> different releases of a package as indicated by the checksum. > > Here the documentation refers to a "Racket version number," which might be > taken to mean a version number of the Racket language: > >> https://docs.racket-lang.org/pkg/catalog-protocol.html >> 8.1 Remote and Directory Catalogs >> In the case of a remote URL or a local directory naming a package catalog, >> the URL/path is extended as follows to obtain information about packages: >> >> pkg and ‹package› path elements, where ‹package› is a package name, plus a >> version=‹version› query (where ‹version› is a Racket version number) in the >> case of a remote URL. > > It seems natural for packages that tightly depend on quickly evolving > features of the Racket language to have a versioning scheme coupled to > Racket's own versions. On the other hand, for packages that work with a > variety of possible Racket versions, it seems to make sense that said > packages would have their own release cycles, compatibility aspirations, and > semantic versioning contract. > > Note that some package managers for evolving languages have two versioning > coordinates, one for the language version and one for the package version. > > Appended below this message is a small racket program that inspects data from > the https://pkgs.racket-lang.org/pkgs-all HTTP endpoint. According to this > analysis, 21% of published Racket packages version using version numbers of > the Racket language. Fewer than 1% of published Racket packages seem to > version using their own version scheme. And 78% of published Racket packages > have only ever filled the version field with "default". > > As the documentation notes, using checksum instead of a version field is sort > of like saying any feature can change at any time to any degree: "A version > is intended to reflect available features of a package, and should not be > confused with different releases of a package as indicated by the checksum." > > My question is this: What is the intended use of the version field in the > Racket package manager? > > Thanks in advance, > > Jeff Henrikson > >> #lang racket >> >> ;; obtain data with: >> ;; curl https://pkgs.racket-lang.org/pkgs-all > contrib_pkgs-all.sexp >> >> ;; relfin is "contrib_pkgs-all.sexp" or similar. >> ;; >> ;; In practice it's one value that comes over the wire, so >> ;; we'll just take the car now. >> (define (read-pkgs5 relfin) >> (letrec ( >> (fin (open-input-file relfin)) >> (iter (lambda (xs) >> (let ((x (read fin))) >> (if (not (equal? x eof)) >> (iter (cons x xs)) >> (begin >> (close-input-port fin) >> xs)))))) >> (car (reverse (iter '()))))) >> >> ;;; Get the versions of a package hash >> (define (versions-of-pkg pkg) >> (hash-keys (hash-ref pkg 'versions))) >> >> ;;; Is there at least one version that appears to be distinct >> ;;; from a racket version? >> ;; Racket version numbers contemporaneous with the remote catalog >> ;; seem to start around version 6. >> (define (package-uses-version-for-package? pkg) >> (not (empty? (filter (lambda (v) >> (and >> (string? v) >> (string<? v "5"))) >> (versions-of-pkg pkg))))) >> >> ;;; Is there at least one version that appears to be a racket version? >> ;; Racket version numbers contemporaneous with the remote catalog >> ;; seem to start around version 6. >> (define (package-uses-version-for-racket? pkg) >> (not (empty? (filter (lambda (v) >> (and >> (string? v) >> (not (equal? v "default")) >> (string<? "5" v))) >> (versions-of-pkg pkg))))) >> >> ;;; Histogram the identified uses of the version field >> (define (classify-version-use pkgs) >> (define (how-used pkg) >> (cond >> ((package-uses-version-for-package? pkg) 'package-versioned) >> ((package-uses-version-for-racket? pkg) 'racket-versioned) >> (else 'no-versioning-used))) >> (define (increment x) >> (+ x 1)) >> (let* ( >> (h (make-hash)) >> (_ (for-each (lambda (kv) >> (hash-update! h (how-used (cdr kv)) increment 0)) >> (hash->list pkgs))) >> (num-by-use (hash->list h))) >> num-by-use)) >> >> (module+ main >> (define pkgs (read-pkgs5 "contrib_pkgs-all.sexp")) >> >> (classify-version-use pkgs) >> ;; '((no-versioning-used . 1472) (racket-versioned . 379) (package-versioned >> . 13)) >> ) > > -- > You received this message because you are subscribed to the Google Groups > "Racket Users" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to racket-users+unsubscr...@googlegroups.com. > To view this discussion on the web visit > [https://groups.google.com/d/msgid/racket-users/cde363b4-f0c4-eb6f-c68f-7033bfa14c3c%40gmail.com](https://groups.google.com/d/msgid/racket-users/cde363b4-f0c4-eb6f-c68f-7033bfa14c3c%40gmail.com?utm_medium=email&utm_source=footer). -- ~slg -- You received this message because you are subscribed to the Google Groups "Racket Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/22ab7663-4998-4d9a-3e6e-61861cdac0bf%40sagegerard.com.
