Fork me on GitHub
#improve-getting-started
<
2023-02-16
>
pez07:02:16

I tried to get an idea of how the the web guides someone into Clojure by asking ChatGPT to write instructions for how to get started. I notice some holes that we will probably want to plug. There is confusion around tooling right off the bat, as we already know. It's also obvious that when getting started with Clojure using Calva, there is a missing step about how to create a project. Unfortunately, the command that GPT suggests for this is not really possible to create in VS Code, but we can probably come close. I'm curious to know what you others take away from these?

dgb2311:02:39

My takeaway is that GPT is wrong here but there's a possibility that it should be right.

pez11:02:51

How do you mean GPT is wrong?

dgb2315:02:21

There's no "Create new Project" command right?

dgb2315:02:41

Maybe I'm just not a ware of it

pez15:02:40

Ah, no, you are right. That's what I referred to with: > Unfortunately, the command that GPT suggests for this is not really possible to create in VS Code

dgb2315:02:41

In recent orange site discourse and in other places this has been a stumbling block for beginners. There is maybe some reasonable default structure for starter projects, talking deps.edn, directory structure with a user namespace for REPL, maybe some comments in there (commands) or something. A main entry point with gen-class etc.

dgb2315:02:42

Or do we actually have something like go mod init , cargo new or npm init etc.?

pez15:02:57

We have clj-new and lein new, GPT seems to have found the latter.

👍 2
chrisoakman16:02:25

This is such a creative idea and use of GPT! I love it 🤓

❤️ 2
seancorfield17:02:25

I think there's a big open question around beginners and "new projects". Is this an application project (i.e., needs -main) or a library project? The former might need uberjar building at some point and (:gen-class) in the main ns. The latter might need JAR building at some point and deployment to Clojars. What about tests? Should we encourage beginners to write tests from the get-go? If so, the project needs both src and test and deps.edn needs a way to run those tests. neil might be a helpful on-ramp here since it can create basic new projects and then add features to them over time -- but then you have to expose the complexity of how to use neil and, more importantly for a beginner, when to add each of those parts. "How to use neil" could be "hidden" behind a bunch of Calva commands but you still have all those extra commands and need to explain when/how to use them. Or you create a rich app or lib project from the get-go -- and beginners have to either be told "you can ignore X, Y, and Z until you need them" or have a full deps.edn and build.clj explained to them.

👍 2
seancorfield17:02:23

Alex and the core team are actively thinking about this -- I've talked to him several times now around this, and plan to spend some time with him at Conj on this. But it's a hard problem to solve.

👍 2
dgb2321:02:19

I just tried out neil and by extension deps-new and build-clj. I really like their easy, just-works utility.

seancorfield21:02:04

build-clj? Oh, I hope not... I'm trying to sunset that wrapper as a Bad Idea(tm).

dgb2322:02:33

@U04V70XH6 this is one of my deps that either neil or deps-new added:

{io.github.seancorfield/build-clj
                 {:git/tag "v0.6.3" :git/sha "9b8e09b"
                  ;; since we're building an app uberjar, we do not
                  ;; need deps-deploy for  deployment:
                  :deps/root "slim"}
I have a build.clj file using some of the [org.corfield.build :as bb]stuff like run-tests clean and uber It all works.

dgb2322:02:15

i used the app template

dgb2322:02:41

It might be a Bad Idea, but my experience was "it's nice how easy all of that was"

seancorfield22:02:46

neil must still be using an older version of deps-new @U04V15CAJ

seancorfield22:02:11

Ah, it's on 0.4.13 and the latest is 0.5.0 that no longer produces projects that rely on build-clj. I'll create a ticket.

borkdude22:02:42

cool, thanks, I can update tomorrow

seancorfield22:02:56

I created an issue for tracking purposes!

👍 2
seancorfield22:02:29

@U01EFUL1A8M I'm trying to encourage folks to use the default tools.build stuff and therefore be able to rely on the official http://clojure.org docs.

👍 2
dgb2322:02:56

Thank you for the heads up!

pez00:02:40

GPT and @U04V70XH6 inspired me to create a mini-starter: https://github.com/PEZ/clojure-get-started-mini

2
borkdude09:02:44

neil v0.1.56 published which upgrades deps-new (and other libs)

🙏 2
pez10:02:01

Should neil go in the resources section of that get started repo, maybe?

borkdude10:02:34

neil is very much focused on getting started with deps.edn quickly! here's the intro blog: https://blog.michielborkent.nl/new-clojure-project-quickstart.html

borkdude10:02:24

the idea of neil is that you can enhance your project with new stuff at any stage of the project, whether you start with a deps-new template (`neil new app foo`) or have a years-old project

borkdude10:02:10

and it's fast!

$ time neil new app foo
Creating project from org.corfield.new/app in foo
neil new app foo   0.11s  user 0.03s system 96% cpu 0.141 total

borkdude10:02:40

and helpful: neil new prints a help text with how to use it

pez10:02:08

Is neil using deps-new under the hood?

borkdude10:02:35

neil new wraps deps-new

borkdude10:02:49

other sub-commands do other stuff, obviously

pez10:02:52

Thanks. I found the deps.edn, but good to know. Updated the project now.

borkdude10:02:27

What are you referring to now?

pez10:02:18

To lein. And to that I added lein to the list of that project's resources section. This project: https://github.com/PEZ/clojure-get-started-mini/

borkdude10:02:50

"I found the deps.edn" - I have no idea what deps.edn you meant there

borkdude10:02:44

For migrating lein projects to deps.edn you also may want to have a look at https://github.com/borkdude/lein2deps

pez10:02:52

Sorry for being in my own context 😃