Feature request for Clojure CLI: Command to create minimal deps project

Question

This is for onboarding newcomers, including those for whom installing additional tools is nontrivial.

From my perspective as a teacher it would be really sweet if an absolutely minimal project could be created with the CLI tools alone. "It must be done by hand or use a 3rd party tool" is an impediment to some of my students, and presumably to other newcomers. In a class setting, with students using different machines and OSes and having different backgrounds, a variety of issues that will seem trivial to developers (such as OSes that add hidden file extensions, editors that encode text, OS path issues, etc.) can produce a lot of discouraging friction.

By "absolutely minimal project" I mean a directory containing a deps.edn that contains {}, and also containing a src folder that contains a single subfolder with the same name as the top-level folder, that in turn contains a single file (might as well be called core.clj) that just contains a minimal ns expression, with a namespace name matching the folder and file names, and nothing else.

I understand that there would be a lot to think about regarding the more general question of whether the CLI tools should support more robust project creation facilities, and if so then what kinds of projects it should create, how this would be organized, etc. But my request here is for something so minimal that I hope it could be considered independently of questions concerning more general facilities. I also hope that this minimal-project-creation feature can be considered independently of the more general issues because I think it would significantly ease the onboarding of some communities of new users.

Comments

Initial thought
Include a `.config/clojure/tools/project.edn` configuration with the Clojure CLI install which would run seancorfield/deps-new when issuing the command `clojure -Tproject create`.

This seems like it would provide a solution to the immediate issue without introducing significant code design into Clojure CLI.

Or the class could clone (or download a zip archive of) a user configuration with relevant aliases and tools that provide this without needing to design a project tool for Clojure CLI directly

> I am assuming git clone is within scope as there are numerous ways to do this with desktop UIs, Web UIs, etc so seems like it would not be beyond the original posters target audience (I've done this approach with people using no-code products many times)

Understanding the value of a ultra minimal project:
I struggle to understand the value of an extremely minimal Clojure project, partly I assume because the request is for what is wanted without defining in detail how it would be used (what is the scope of the lesson plan)

Elaboration on how Clojure is being taught would and the scope of what is being taught would help in understanding the value of this.  Otherwise is seems very specific to the original posters needs rather than a useful tool for the community.

My concerns would be

1. relies on implicit configuration knowledge

Having a project configuration file with only a `{}`  surely begs questions on how does that work, leading on to discussion on how the Clojure CLI brings in the Clojure dependency and adds `src` to the class path

2. No examples to support learning

Including a minimal `:paths` and `:deps` config would provide a simple way to show the syntax required when adding further config (its hard to tell if this is out of scope)

The same could be argued for inclusion of an alias, e.g. a test runner

3. Creating something for a specific use case

I dont think it is prudent to introduce a project creating tool within the Clojure CLI without considering the wider community needs.  At least not as a release feature.  

4. Reinventing

clj-new and deps-new already provide a way to create projects and a minimal scratch template seems to cover the original posters needs (with my limited understanding)
https://github.com/seancorfield/deps-new#create-a-minimal-scratch-project

This could be part of the install instructions for a class (along with Java & Clojure CLI) or a user config copied onto the students computers.

There are more issues, but that really depends on the scope of the original posters request.

---

On "Understanding the value of an ultra minimal project," my current use case is an undergraduate course in which Clojure is used as the programming language, but in which neither Clojure nor software development are the primary focus of the course.

My current course is on Evolutionary Computation, but I've done similar things for courses on AI and other topics, and I know other computer science faculty who do similar things in other courses. Ideally, students would be able to install one thing and then be able to get down to typing/editing/evaluating/saving Clojure expressions related to the topics we are studying (evolutionary computation in my current case). Maybe we can't get quite to the "install one thing" ideal, but it would be great to make the path from zero to writing/editing/running Clojure code as short as possible. I think this is true not only for students in courses like the one I'm teaching now, but also for people who may be coming to Clojure independently in a range of other contexts.

If deps.edn is a supported way to manage projects, and there really is a minimal "new document" project structure, then it would be really nice if the installation you're already doing (CLI tools) would give you a way to make a minimal project.

My understanding is that we just need a deps.edn file, which must contain a map, but that map can be empty. And we need an src directory. And since single segment namespaces are strongly discouraged we need a folder within src. Then our new document, empty aside from a properly constructed ns expression, will live within that folder.

I realize that once we consider anything else there are a lot of options and it's not clear how to organize them. But I don't think that what I suggested gets into that territory.

Because the tools we're currently using for my course don't make projects, I do currently distribute a minimal project  through the course's website. But this isn't ideal for a couple of reasons. For one thing, I have to give my minimal project a name, and students have to change both directory names and file contents to change it. For students who aren't in my class (and, I suspect, for others coming to Clojure from a variety of perspectives and with a variety of backgrounds and purposes) this is another thing to have to find and figure out before one can begin writing/editing/running code.

On John Stevenson's specific concerns:

1. Students in my class won't necessarily need to know how {} works in deps.edn, or how CLI brings in the Clojure dependency, or anything about class paths. If they end up needing to know any of this, they can learn it later. In any case, it'd be great if knowing this stuff wasn't required for beginning to write/edit/run Clojure code.

2. I agree that examples to support learning are a great idea. I'd like to see more. Last I checked, I thought the materials on clojure.org about how to specify dependencies jumped to fancy examples without making it as clear as I'd like how to do the basic stuff. But I do think this is out of scope here.

3. I don't think this is really such a specific use case. Most word processors have a "new document" feature, and although I guess you could say this is just for the "special use case" of people who don't have pre-existing templates or separate software for creating new documents, I think a "new document" feature is a pretty useful thing for a lot of people. Since projects are necessary for many Clojure editors and tools, the "new document" feature for Clojure would make a project. In this analogy, a minimal project is like the blank document you get in most word processors.

4. It's great that there is other software that creates projects. It would be even better if we didn't need other software to create a minimal project.

Answer 1

Logged as https://clojure.atlassian.net/browse/TDEPS-242

Comments

Thinking  out loud here... If we consider the special case, my-first-clojure-project, and not some general create-any-project, this could be a nice part of the get-started-with-clojure journey. The project created could be similar to this https://github.com/PEZ/clojure-zero, without the web based stuff and not Calva specific. The point is that it could have very little content, and the README can provide guidance for what to do next. I'll throw in another starter-project of mine as an example: https://github.com/PEZ/clojure-get-started-mini

The command line for creating the project could support options for some little configuration, and the script could drop into prompts for any options not provided. Options could include:
* Create Clojure or ClojureScript or both starter?
* create README with get-started instructions?
* create instructions for which editor? Calva/CIDER/Cursive
* include get-started comments in the source files?
* include get-started material for <editor>?

The get-started material content could be crowdsourced in a manner similar to Calva's getting-started material: https://github.com/BetterThanTomorrow/dram (Which needs more think when it comes to configuration, but anyway, it's just the concept I want to highlight, not the solution.)

---

While all of these configuration options and getting started materials might be wonderful, it's not obvious what the right ones would be and it might be counterproductive to include a lot of prompts/text/etc that might be confusing and unnecessary in some contexts.

If I understand correctly, there is little that is controversial about the minimum project that is required. For example I think that the structure I've defined is close to the minimum for Calva to open it and let you work with it, with the only not-completely-necessary part being the avoidance of a single segment namespace.

So it would be great if CLI tools could make minimal projects of this sort. All of the "getting started materials" could be available elsewhere, and then if people disagree about the contents they can make alternative versions. In the meantime, new users would be able to begin working in Clojure without getting a separate project-creation tool or dealing with creating projects from scratch.

---

It doesn't need to present a lot of options to the user. Could be a project-type option, which if omitted presents a prompt:

1. Create a blank Clojure project
2. Create a blank ClojureScript project
3. Create a blank Clojure + ClojureScript project
4. Create  a Getting Started project

It would be a bit like when creating a new document in Pages or Keynote. It opens up a dialog where you can choose to create a blank document or from a template. Google Drive does something similar:

https://user-images.githubusercontent.com/30010/224144517-d9fce7d3-1feb-40ea-9c63-3de0f0ee1b70.png

Only if you choose the non-blank option would you get some more prompts. A lot of tools for creating projects work like this. When creating a VS Code extension you are adviced to use `yo`, which lets you configure the project a bit using prompts: https://code.visualstudio.com/api/get-started/your-first-extension