practicalli / practicalli/clojure

clj-new project naming

Open
#224 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

clojure cli
Dominant language
Makefile
Stars
117
Forks
36
PR merge metrics
No merged PRs in 30d

Description

I'm trying out this library clj-new. One thing I'm trying to understand is that it has a syntax for creating a new app that it describes like this:

clj -A:new app myname/myapp

When you run this you get a directory structure that looks (in part) like:

src
|--myname
    |--myapp.clj

Can anyone explain to me why this tool likes to include the author's name in the directory structure?

When publishing a Clojure project it should have a unique group ID (and artifact ID) on clojars.org -- so this aligns with that. If you look in the generated pom.xml, you'll see that it would publish it as myname/myapp (with whatever version).

And if your project is going to be used by other people, you want it to not conflict with any of their code, so the namespaces should all have a unique stem. Your GitHub ID (your account name) is a good group ID and a good root namespace.

You could also choose your company name, or your company's reversed domain name -- the way org.clojure/clojure, org.clojure/java.data are set up.

What threw me about the username in the directory structure actually has more to do with the namespace structure. You end up with myname.appname rather than appname.namespace1. I feel like the latter is more familiar to me -- but admittedly I have zero experience publishing libraries.

If two people published something called appname with the namespaces like that, they would conflict and no one could use them both together. If their libraries have namespaces that start with myname (and yourname) then they can be used together.
It's why, for example, all of core and all the Contrib libraries have clojure as a prefix in their namespace names even tho' it may seem redundant.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue contains a question about clj-new's myname/myapp project and namespace layout but names no documentation file or entry point. Start by locating the repository's clj-new or project-naming guidance, then document why the author name or group ID prefixes namespaces. Done means the rationale is clearly explained for readers unfamiliar with publishing Clojure libraries.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.