3 ms·

I think your pattern is right except for "its weird and undocumented" - I have found the maintainers are superb at docs - e.g. deps.edn - there is a "Guide" h

I think your pattern is right except for "its weird and undocumented" - I have found the maintainers are superb at docs - e.g. deps.edn - there is a "Guide" https://clojure.org/guides/deps_and_cli https://clojure.org/guides/deps_and_cli there is a "Getting Started" https://clojure.org/guides/getting_started https://clojure.org/guides/getting_started (it's branded as an overall Clojure getting started but the core of deps is just the clj/clojure command line tool you would use to install clojure) there is a deep "Reference" with a "Rationale" https://clojure.org/reference/deps_and_cli https://clojure.org/reference/deps_and_cli spec Spec Guide - https://clojure.org/guides/spec https://clojure.org/guides/spec Spec Rationale https://clojure.org/about/spec https://clojure.org/about/spec Spec API reference https://clojure.github.io/spec.alpha/ https://clojure.github.io/spec.alpha/ Spec resources (brief) https://clojure.org/community/resources#spec https://clojure.org/community/resources#spec (Rich Hickey also gave a couple of spec talks that are on YouTube) Also, for my money, deps.edn is way more composable than lein, does not feel weird to me at all. Ditto for spec vs prismatic schema which preceded it. I think the latter case is one where people were more miffed that the official solution displaced a community beloved tool, but to me it genuinely seems really well thought through. There are some flaws discussed in the Rich Hickey talk "Maybe Not" which led to an experimental (still beta) spec2 but spec1 I still find miles ahead of what's available for the languages I've worked with.

rch 4y ago
Excellent doc references, and FWIW I share your perspective on the tools.
roenxi 4y ago
"Superb" is not the word for deps.edn documentation. It is certainly documented but the gap between most Clojure documentation and the deps.edn documentation page is big. I suspect Rich wrote most of it but left the deps.edn page to someone else.The deps pages have a knack for includng pages of waffle that doesn't help to solve the current problem. If a newbie is trying to debug {:deps {ring/ring-devel {:mvn/version "1.9.6"}} {ring/ring-core {:mvn/version "1.9.6"}}} => Error building classpath. Error reading edn. Map literal must contain an even number of forms They have to notice that while they got 80% of their maps right, the file itself if a map with 3 forms. This is compounded by the fact that there are no examples of a multi-dependency project in the getting started page! If you know Clojure, this is an easy puzzle. For rookies, they didn't use (map) so the error message will probably trick some percent of them. I don't think the deps documentation has been validated to provide what people actually want to know. Technically it is probably thorough, but "Superb" is a high bar it does not reach. Probably the proper approach is learning deps by copying other people. Trying to learn it from the docs didn't work for me (it did for the rest of Clojure, so that was an unpleasant change).
- e12e 4y ago
  Out of curiosity - what is the correct form in this case? Ed: I'm guessing a key => list of deps, maybe?
  - grumpyprole 4y ago
    I think you might be asking for a type :)
    - jdminhbg 4y ago
      Not really. This is a syntactic error, not a type error. To expand, this is the equivalent of something like {"a": 1, "b":}. The type checker in something like Typescript wouldn't ever come into play, because it's not legal syntax to begin with.
      - grumpyprole 4y ago
        The parent was asking for the correct form, the syntax of EDN is necessary but not sufficient to specify this. A type (or a schema) is needed. Even if documented manually ad-hoc, that is better than nothing and would stop people needed to search the internet for examples.
  - roenxi 4y ago
    It should be: {:deps {ring/ring-devel {:mvn/version "1.9.6"} ring/ring-core {:mvn/version "1.9.6"}}} There was one too many map.
- puredanger 4y ago
  These are useful comments and issues are welcome at https://github.com/clojure/clojure-site/issues https://github.com/clojure/clojure-site/issues
  - roenxi 4y ago
    smoothly changes gears ... although of course there can be no question that the deps documentation is managed by a man of patience, talent and extreme skill to whom we are all thankful. Sorry, I had a bad time learning deps and the frustration still haunts me.

rch 4y ago

Excellent doc references, and FWIW I share your perspective on the tools.

roenxi 4y ago

"Superb" is not the word for deps.edn documentation. It is certainly documented but the gap between most Clojure documentation and the deps.edn documentation page is big. I suspect Rich wrote most of it but left the deps.edn page to someone else.The deps pages have a knack for includng pages of waffle that doesn't help to solve the current problem. If a newbie is trying to debug {:deps {ring/ring-devel {:mvn/version "1.9.6"}} {ring/ring-core {:mvn/version "1.9.6"}}} => Error building classpath. Error reading edn. Map literal must contain an even number of forms They have to notice that while they got 80% of their maps right, the file itself if a map with 3 forms. This is compounded by the fact that there are no examples of a multi-dependency project in the getting started page! If you know Clojure, this is an easy puzzle. For rookies, they didn't use (map) so the error message will probably trick some percent of them. I don't think the deps documentation has been validated to provide what people actually want to know. Technically it is probably thorough, but "Superb" is a high bar it does not reach. Probably the proper approach is learning deps by copying other people. Trying to learn it from the docs didn't work for me (it did for the rest of Clojure, so that was an unpleasant change).

e12e 4y ago
Out of curiosity - what is the correct form in this case? Ed: I'm guessing a key => list of deps, maybe?
- grumpyprole 4y ago
  I think you might be asking for a type :)
  - jdminhbg 4y ago
    Not really. This is a syntactic error, not a type error. To expand, this is the equivalent of something like {"a": 1, "b":}. The type checker in something like Typescript wouldn't ever come into play, because it's not legal syntax to begin with.
    - grumpyprole 4y ago
      The parent was asking for the correct form, the syntax of EDN is necessary but not sufficient to specify this. A type (or a schema) is needed. Even if documented manually ad-hoc, that is better than nothing and would stop people needed to search the internet for examples.
- roenxi 4y ago
  It should be: {:deps {ring/ring-devel {:mvn/version "1.9.6"} ring/ring-core {:mvn/version "1.9.6"}}} There was one too many map.
puredanger 4y ago
These are useful comments and issues are welcome at https://github.com/clojure/clojure-site/issues https://github.com/clojure/clojure-site/issues
- roenxi 4y ago
  smoothly changes gears ... although of course there can be no question that the deps documentation is managed by a man of patience, talent and extreme skill to whom we are all thankful. Sorry, I had a bad time learning deps and the frustration still haunts me.