Fork me on GitHub
#tools-deps
<
2022-12-05
>
skylize00:12:31

Diverting to new thread here, as sharp tangent from the Calva thread this comment came from. > @seancorfield it's a great service to civilization, that someone keeps up with Clojure Deps. Its direct-to-git dependencies are "obviously" the long-term Right Thing To Do. Hopefully someone will ring a bell over my grave when Deps is finally finished and stable and has a command line as simple as Lein's. -- @phill What about the CLI tools do you feel is unfinished? What about its interface do you feel is less "simple" than Lein's?

seancorfield01:12:42

Thanks for creating this thread @U90R0EPHA - I'll be very interested to hear what folks say (although we've had several threads complaining about the exec-style command-line arguments so that won't be anything new).

☺️ 1
Alex Miller (Clojure team)01:12:39

btw I finalized a path with Rich last week to move tdeps out of alpha and I’ll start working through that over the next couple of weeks

1
bigfoot 1
👍 2
dumrat07:12:59

Lack of templates. I'm aware of clj-new but for beginners looking to just get started with a template, it's painful.

seancorfield17:12:15

@UC1DTFY1G Interesting. Can you elaborate? What sort of templates? Is this a discovery issue or something else? What changes to the docs/ecosystem would help address this?

skylize18:12:09

I generally use deps-new for bootstrapping. I assume I can make a custom template for it, and keep intending to do so. But I haven't gotten around to it because last I checked the readme offers no meaningful guidance for such customization. Knowing I need to reverse engineer one of the built in templates (and maybe also the library?), I fail to find the motivation to get going. I also don't know of any other templates besides the ones included. Do they exist somewhere? Discovery here could be as simple as a wiki page on the deps-new repo where people can add links to published templates. --- I think all of that's likely tangential to @UC1DTFY1G's concern though. My guess is the real issue there is likely that neither clj-new nor deps-new get any mention in the official docs, because they are not part of Clojure's official suite of tools. How to get a project up and running properly without a basic skeleton is not obvious as a beginner. Maybe some extra-minimalist reproduction of deps-new could be included the either tools.deps or tools.build?

👍 1
seancorfield18:12:07

A PR was recently merged to add a place to the readme for folks to have their deps-new templates listed: https://github.com/seancorfield/deps-new#templates -- and there's an expanded section on how to write templates and make them available https://github.com/seancorfield/deps-new/blob/develop/doc/templates.md -- happy to take PRs to continue to improve this!

🎉 1
seancorfield18:12:57

(even tho' I wrote and maintained boot-new, clj-new, and deps-new, I pretty much never used any of them -- I always created new projects from scratch)

skylize18:12:55

It's easy to see not bothering with such tools once you know what you're doing. But there are a surpising number of things you need to know that a skeleton can let you put off for learning later. A few things that come to mind: For a real project you need a separate src and test folder, where namespaces parallel directory structure, test namespaces parallel source namespaces, and dashes are replaced with underscores in the file names. You need paths specified for building the classpath. You need to know that test paths and test dependencies, if any, need to be in an alias so they aren't destined to be included in your production build. And I haven't even touched on the possibility of trying to build a release.

👍 1
seancorfield18:12:18

I would love to see deps-new mentioned on http://clojure.org as a way to set up "complete" new projects and it could even have its tools EDN file installed as part of the Clojure CLI -- but I doubt that would happen. Given that it is "just" a thin wrapper around tools.build and it's already EPL1 and has almost no contributors except me, it probably wouldn't be much work to get it turned into a Contrib project, if that would make it more palatable to the core team, but again I don't really see that happening... @U064X3EF3?

Alex Miller (Clojure team)18:12:41

most of what the new templates do, I don't think is needed, and I think it's telling that many people don't use them. I'm not opposed to building some "new" type functionality into the cli but I would like to think about it more - I think the neil approach of adding slices of stuff is a better approach. on build-clj, I actually disagree with the approach of wrapping here. the whole point of tools.build is to start with something simple and grow it, but build-clj hides that (and papers over actually understanding what you're build is and does) and makes it harder to grow it later. I would actually rather have templates in this scenario that don't use a wrapper. but maybe there are things we can do in tools.build to lessen the desire for the wrapper in the first place.

seancorfield18:12:44

We're not talking about build-clj -- just to be clear. deps-new just uses tools.build, not build-clj

seancorfield19:12:33

> I think it's telling that many people don't use them Isn't this perhaps a Catch-22 since it isn't mentioned on http://clojure.org so folks don't know about it? There seem to be plenty of new Clojurians asking about guidance for this sort of thing and folks usually point them to clj-new or deps-new...

seancorfield19:12:34

(and if changing the generated projects in deps-new to not use build-clj would make it more palatable, I'm happy to do that 🙂 )

seancorfield19:12:52

But, yes, overall I'd like to see something official that makes it easy for new Clojure users to create "fully-featured" simple application and library projects, whatever form that takes -- and I'm happy to contribute to that with whatever guidance the core team want to offer. As with depstar, I'd much rather the official offerings meant I could retire clj-new and deps-new 🙂

dumrat01:12:07

Imagine you don't know Clojure. And you see someone doing some cool things with it and you want to try it out. There's a lot of people who are so used to doing npm hairball or whatever and just write js and not worry about how the build system works. Perhaps this person would later be interested as to how to create his own project from scratch. But with Clojure, expecting new users to learn Clojure which is quite different to the majority of languages and then learn new IDEs, extensions, repl stuff, and on top of all this, figuring out how to create a project from scratch, this is too much. All he might want to do might be to just start up a web server and explore how that feels. Apologies if I'm wrong, but I think this is one more barrier to entry. I feel there should be some "standard" way to quickly get a common type of project underway without having to think. Experts in the language can choose not to use these stuff, but for beginners there should be an easy and a standard way to do it. deps is the right place for it as it is the official thing.

seancorfield16:12:55

@UC1DTFY1G Maybe something like clojure -Ttools create-app :name mycool/newapp or clojure -Ttools create-lib :name dumrat/cool-lib out of the box? (I suggest -Ttools since that's "built-in") I suspect the sticking point would be what's the bare minimum that should be in such generated projects, since "The Clojure Way" is somewhat minimal and composable.

dumrat16:12:55

@seancorfield I really don't mind it being verbose (Though I think some would take issue even with that). As long as it works out of the box and documented somewhere official, I think it'd be great. I think I understand the reluctance to make tools do more than they absolutely have to, and perhaps I'm wrong. But I think we live in an age where attention spans are extremely short. One thing Clojure excels at (according to me is) helping the programmer hold his attention - primarily REPL + not being statically typed. Even someone like me can spend hours at the REPL and my attention span is extremely short. But getting someone to a decent REPL is perhaps the hard part. Just what I think. I don't have any evidence to back any of this up 🙂

seancorfield16:12:05

I think one of the key aspects of a "good" Clojure experience for new developers is an editor that feels approachable with a really good story for connected REPLs so that folks can get past the "typing-into-a-REPL" stage of learning to actually doing stuff. I think that's much more important for onboarding than "creating a new project" but I understand why folks obsess about the latter. I think Calva is the only good option right now for the former (and then there's the difficulty for the Clojure core team of how to guide people to that without seeming to "favor" one editor over another and thus implicitly criticizing other editors -- this is a really tricky thing to navigate for communities).

👍 1
dumrat17:12:02

ok, I don't understand the stuff in parens - why can't we just have getting started guides for all major IDEs? And it just sucks that there's no good web based integrated REPL that can be showcased in official site. I think I checked a few languages sometime back and at least Rust and Elm had an interactive playground just one click away from the main site. Ironic that Clojure with one of the best REPLs doesn't have this. I haven't tried Replit in a long time, but last I tried, it didn't work very good for clojure. Sorry, I don't mean to be mean or blame anyone. I'm very happy with Clojure. Just that recently I've been wondering why more people don't see the light 😄

Alex Miller (Clojure team)17:12:00

I welcome your getting start guide PRs....

Alex Miller (Clojure team)17:12:48

I know this seems like an obvious answer, but the problem is that an expert needs to write it, and the experts are people that work on it mostly, and when they work on it they inevitably want it in their own docs, not on the main clojure site. I have been asking people to write these guides for 10 years and no one has ever even started one. Inevitably I will probably write some of them, but it's a huge time investment, not just at the start but continuously to maintain it.

👍 1
dumrat17:12:25

@U064X3EF3 Beginner here, but will try to add something. 🙂

Alex Miller (Clojure team)17:12:56

I don't actually think that having a repl on site is important - you can't get any of the affordances with an editor connected repl or structural editing that you get from a real environment. If you are serious about trying Clojure, and there is a well-oiled path to that, then people should take the extra few minutes to do so. the Calva gitpod stuff is pretty slick and my best suggestion atm.

👍 1
seancorfield17:12:37

I agree -- for the same reason that it's important to get people past the typing-into-a-repl stage: that's not how you work with Clojure "for real" and it's a very limited experience. Having community members contribute (and maintain) "Getting Started" guides for the major IDEs to http://clojure.org would be the path forward here. Based on the last State of Clojure Survey, that's Emacs, Cursive, VS Code/Calva, and I believe vim/neovim was next... But those are four very different audiences and likely to be at least four different contributors -- and you don't really want to duplicate each editor's Getting Started guide (if there is one) but mostly just point to it (right @U064X3EF3?) which would make the PR for clojure-site pretty small for Calva 🙂

seancorfield17:12:05

(getting people to contribute is hard: years ago, I got tired of people complaining that they couldn't easily contribute to the clojure.java.jdbc docs because of the Contrib process with Jira and patches so I moved the docs to https://clojure-doc.org/articles/ecosystem/java_jdbc/home/ where folks could easily submit PRs etc... and the result was "crickets"... so all those people claiming the Contrib process was an obstacle were just complaining about the process and not really intending to contribute!)

Alex Miller (Clojure team)17:12:55

I actually don’t think a set of links is the right answer (having also tried this in the past). There is a narrow set of things to cover and a lot of value in having that same set covered for multiple envs in a consistent way. Maybe I should just write bad versions and then people would correct them :)

😆 1
😄 1
skylize04:12:19

> I think one of the key aspects ... for new developers is an editor with a really good story for connected REPLs [to] get past the "typing-into-a-REPL" stage ... to actually doing stuff. I think that's much more important for onboarding than "creating a new project" I would argue that "creating a new project" is even more important than editor integration for getting to "actually doing stuff". If you want to make any kind of progress on anything more complex than toy examples, you need to be able to save your accomplishments into a file, and then be able to load those files back into a repl to run again later. If you don't even know how to set up a functional main namespace to start working out of, editor evaluation is not really going to help you. Besides that, good editor tooling is mostly agnostic to the choice of Leiningen or Clojure CLI. And the point of this thread is not to try and solve all aspects Clojure's New User Story. The point is to discuss the contrast between the Clojure CLI Tools New User Story and the Leinengen New User Story; to hopefully shake out what can/should be done to address the widely held opinion that beginners should be pointed toward Leiningen from the outset because "it's easier".

skylize04:12:23

> so all those people claiming the Contrib process was an obstacle were just complaining about the process and not really intending to contribute! Reasonable but unsound conclusion. Could be those people really did want to contribute, but by the time you made it easy they had moved on and had other things on their mind. But, yeah. Getting people to follow through on thankless unpaid labor in their free time is certainly not easy or straightforward.

skylize04:12:32

> Maybe I should just write bad versions and then people would correct them Funny but true. Sounds like a brilliant plan to me. yoda

seancorfield04:12:01

> Could be those people really did want to contribute, but by the time you made it easy they had moved on and had other things on their mind. I moved it while folks were complaining about the Contrib process so, no.

seancorfield04:12:56

> I would argue that "creating a new project" is even more important than editor integration for getting to "actually doing stuff". I meant that we know how to solve the "creating a new project" issue -- we just have to either document it or put something into the core tooling. The editor-connected-repl workflow seems much, much harder for us to teach to beginners, and we don't yet seem to have a good handle on how to address that. Showing someone once how to create a new project is sufficient. It's a simple step to teach. Teaching an ongoing workflow or process is harder 😞

George05:12:03

> The point is to discuss the contrast between the Clojure CLI Tools New User Story and the Leinengen New User Story; to hopefully shake out what can/should be done to address the widely held opinion that beginners should be pointed toward Leiningen from the outset because "it's easier". I am about a month into learning Clojure and started with the CLI; the book I'm following uses Lein but I convert everything to the CLI. The CLI syntax definitely is alien at first, but the guides on http://clojure.org are IMO very good. So much of beginner programming is rote following of examples personally I don't think focusing on the command line syntax is that important. Though I started out creating projects by hand eventually I found using a template from deps-new a big help as there are many little things that I didn't even think about when structuring a project. To that point though modifying that template for my own use I found to be quite easy.

👍 3
1
seancorfield05:12:41

We never did get an answer the original question "What about the CLI tools do you feel is unfinished?" 🙂

skylize05:12:08

The comments that led me to start this thread were from @phill, who has not decided to join in on further conversation. So we may not get any response that answers that question directly.

🙁 1
bringe03:12:29

I think putting getting started guides directly on the site for different editors would be great. I’d be happy to write one up for Calva. I think it would be good to start from absolutely no dependencies (no VS Code, no Java, etc.) to evaluating code from project files with a REPL connected to Calva. Maybe following, for each editor guide, some framework to keep the guides simple and minimal would be a good idea - something like: 1. installation of deps 2. creation of a basic project 3. start and connect to a repl 4. evaluate forms and see output For any other information, the reader can be directed to the docs of the editor, or other guides on http://clojure.org, where appropriate. Some other possible guidelines: • Every guide should use the Clojure CLI for managing deps and starting the REPL • Maybe each guide should avoid OS-specific details or any details about how to install the deps, instead pointing to official docs for that information. Or maybe it’s good to go into those details…

bringe03:12:38

I’d be happy to get feedback on the above and any other guidance you might have, @U064X3EF3.

Ben Sless17:12:50

I think it's worth mentioning neil here as a pretty decent "hit the ground running" tool for beginners which I don't think papers too much over what actually goes on