Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consider renaming the project to make it easier to differentiate between it and nREPL #375

Closed
bbatsov opened this issue Sep 23, 2013 · 70 comments

Comments

Projects
None yet
@bbatsov
Copy link
Member

commented Sep 23, 2013

I believe that the current project name is problematic for a number of reasons and we might consider renaming it. Here's the problems:

  • Confusion between nREPL and nrepl.el online.

Nobody actually calls nrepl.el nrepl.el - you'll find lots of articles about nrepl and Emacs, but not much about nrepl.el and Emacs if you do a web search. This makes it very hard to find something about nREPL itself, since most search results are actually about nrepl.el.

  • Confusion between nREPL and nrepl.el in the code and the documentation.

The code of nrepl.el is pretty confusing for newcomers at some places because everything is nrepl- something and we have some pretty absurd naming situations from time to time (we had nrepl-nrepl-buffer at some point). The documentation is also confusing since often it refers to nREPL or nrepl.el just by nrepl.

  • nrepl.el is more than just an nREPL client.

Sure, nREPL provides the basis from most of the functionality in nrepl.el, but ultimately nrepl.el is a Clojure programming environment similar to an IDE. The current name of the project hardly makes this apparent.

I think the community would be better served if we draw a clearer line between client and server in the naming department (like swank and SLIME, foreplay.vim and nREPL, etc).

I have no concrete ideas about a new name, but I've thought about the complexity of renaming the project. Since a lot of resources refer to it I plan to leave an empty repo named nrepl.el behind pointing to the new project. We'll also keep around the nrepl.el package on Marmalade at least for a while. ritz is the only major project depending on nrepl.el, so I guess the fallout from the renaming would be minimal.

/cc @hugoduncan @kingtim @purcell @technomancy @samaaron

I'd love to hear your thoughts on the subject.

@purcell

This comment has been minimized.

Copy link
Member

commented Sep 23, 2013

I'd be strongly against renaming nrepl.el. I just don't see that the benefits are worthwhile. If there's clojure-related stuff in nrepl that is more general, then we should split that out into a separate package, and have that depend on nrepl.el.

The documentation can, of course, be made clearer if necessary.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Sep 23, 2013

Technically speaking the only thing that's really depending on nREPL is the evaluation and connection code. In theory it shouldn't be hard to use an nREPL alternative (but this is unlikely at this point) with nrepl.el. So if we end up with two packages, there'll be almost nothing in the nrepl.el package which would not be much different from directly renaming the project.

Personally I'm not exactly thrilled to do such a change, but yesterday I noticed that searching for nREPL returns just one non-Emacs related result in the first few pages of results which reminding me of my other annoyances with the name. And the nrepl-nrepl moments in the code have been bugging me for a quite a while now. Anyways, I can live with it as is. It's up to the Emacs Clojure community to decide :-)

@pmbauer

This comment has been minimized.

Copy link

commented Sep 23, 2013

Is this generally confusing or only confusing for a few people? Having done the same google search for nrepl, I'm not seeing the confusion; in fact the first hit is for the nrepl project proper.
I've never found this to be an issue and renaming is significant overhead for unknown gain.

@technomancy

This comment has been minimized.

Copy link
Contributor

commented Sep 23, 2013

My vote is to ensure we are consistent and precise in the docs and possibly include a "Terminology" section in the readme.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Sep 23, 2013

@pmbauer Obviously it's not confusing for the people that are known what they are looking for and what nrepl.el and nREPL are :-) The one non-Emacs result I mentioned is indeed the nREPL project's home. Anyways, you should consider the fact that many of the people who come upon nrepl.el don't know even how to start it, let alone differentiate between two projects with almost the same names.

And the search results in Google are not something I care that much about. Personally as one of nrepl.el's maintainers I'm mostly interested in having no ambiguity in the code and the docs and as I already mentioned a different name will help a lot in this department. If someone can come with a way do resolve all the ambiguities in an alternative way - I'm obviously open to suggestions. Just to illustrate the problem with an example - the ops like nrepl-doc, nrepl-source, etc are invoked in an nREPL session called nrepl-tooling-session in our code. I know what this session exactly is, but I'm pretty sure casual readers of the code will be confused if they do no consult its docstring - is this some nREPL session on an nrepl.el client-side session?

@samaaron

This comment has been minimized.

Copy link
Contributor

commented Sep 23, 2013

How about enrepl?

@pjstadig

This comment has been minimized.

Copy link
Contributor

commented Sep 23, 2013

no

@samaaron

This comment has been minimized.

Copy link
Contributor

commented Sep 23, 2013

no is a great name for the project!

@klang

This comment has been minimized.

Copy link
Contributor

commented Sep 23, 2013

Swank Clojure was deprecated just over a year ago an nrepl.el was hailed as the replacement. nrepl.el is a fine name and does indicate connection with emacs right there in the .el part.
Please don't confuse people further by chaging the name. It's hard enough for new emacs users as it is.

@alexander-yakushev

This comment has been minimized.

Copy link
Member

commented Sep 23, 2013

I don't think it's a good idea to rename the project at this point of time. People who distinguish between nRepl and nrepl.el use both these names correctly; for people who don't it is actually better not to care that those are two separate entities. "Clojure has a REPL, I do nrepl-jack-in from Emacs to run it, I'm happy".

@pjstadig

This comment has been minimized.

Copy link
Contributor

commented Sep 23, 2013

@samaaron haha

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Sep 23, 2013

@samaaron Yep, even such a small difference would make a big improvement IMO.

@klang Renaming the project has nothing to do with it's status :-) .el signifies a bond with Emacs indeed, but dots in project names are generally not cool and should be avoided. Even the official packages are currently named nrepl (not nrepl.el), which blurs the line between the two nrepl projects. Also nrepl.el could be a project, but could also be just an Elisp source file.

@alexander-yakushev As I already said several times - it's not only about distinguishing them externally, it's about distinguishing them internally. Consider this bit of code:

(defun nrepl (host port)
  "Connect nrepl to HOST and PORT."
   ...
)

(defun nrepl-default-port ()
  "Attempt to read port from target/repl-port.
Falls back to `nrepl-port' if not found."
...
)

In the first example a more correct docstring would be "Connect nrepl.el to an nREPL identified by HOST and PORT.", but that sounds a bit odd to me. nrepl.el, could very well be just a file name. Assuming that once project is nrepl and the other is nREPL the description would sound somewhat absurdly to newcomers.

In the second example - what is the nrepl-default-port - is the default port the client would try to connect to or the default port the server would be listening to? There is a difference between having something that's good enough and something that's really good :-) I'd very much like to hear ideas about disambiguation in scenarios like this, that don't involve naming changes. Maybe we could use client and server here and there in function names?

@alexander-yakushev

This comment has been minimized.

Copy link
Member

commented Sep 23, 2013

Maybe we could use client and server here and there in function names?

Sounds pretty simple and solid.

@jsyeo

This comment has been minimized.

Copy link

commented Sep 24, 2013

What? They are different? Now I'm confused.

@darth10

This comment has been minimized.

Copy link

commented Sep 24, 2013

I feel nREPL and nrepl.el are distinguishing enough, since the later is just a client for nREPL written for Emacs.
Let's just stick to nrepl.el.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Sep 24, 2013

@darth10 You do realize that in the code we cannot use neither nREPL, nor nrepl.el, right? :-) Different case unfortunately isn't the best form of differentiating stuff.

@darth10

This comment has been minimized.

Copy link

commented Sep 24, 2013

Then, I'd vote for changing just the server's name 😄.

I know you mentioned that online material like blogs don't refer to nrepl.el, but I feel that's not true for published literature. Of course, some books just mention "nREPL". Just my two cents.

@nilswloka

This comment has been minimized.

Copy link

commented Sep 24, 2013

I actually like the name (but that might not be a valid argument). I also assume that almost all people who search for nREPL and/or nrepl.el are able to understand the difference after a look at the project pages. So even if it's confusing at the first glance, I don't see any harm done. Renaming nrepl.el on the other hand might actually make it more difficult to find an nREPL-client for Emacs - and making the newcomer's Clojure IDE experience more difficult can hardly be a good idea :)

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Sep 25, 2013

Or just many people write Clojure + Emacs and see a reference to nrepl.el :-) After all vim's equivalent is named foreplay and people still manage to find it. It's likely for people that have already used nrepl.el to know that there is something named nREPL that does most of the heavy lifting, but I'm pretty sure that's not the case for new users. After all many SLIME users don't even know what swank is... And I'm absolutely certain that no new users searches for an "an nREPL client for Emacs" :-) Btw, I'll probably change that description anyways, since it's a bit of misnomer.

So far most of you have not mentioned the issue that bothers me most - how do we cleanly differentiate two things with the same name in the source code.

@purcell

This comment has been minimized.

Copy link
Member

commented Sep 25, 2013

So far most of you have not mentioned the issue that bothers me most - how do we cleanly differentiate two things with the same name in the source code.

Perhaps use a different term to refer to nrepl, e.g. backend, server, session.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Sep 25, 2013

@purcell You mean nREPL ;-) Maybe, still I'm frustrated that the server/backend actually has a name that we've recycled for the client. Since session carries extra meaning with nREPL using it is not an option.

I liked your suggestion for splitting the thing in two - one package remains nrepl - it's only the backend related stuff. The client package becomes something else. That would avoid some problems and would make the code more modular, which generally is a good thing.

@alexander-yakushev

This comment has been minimized.

Copy link
Member

commented Sep 25, 2013

I think having separate names for server and client (like SWANK and SLIME)
might be better if done from the start, but renaming a mature project to
fix small confusion in the code (which can also be fixed differently) is an
overkill.
On Sep 25, 2013 10:23 AM, "Bozhidar Batsov" notifications@github.com
wrote:

@purcell https://github.com/purcell You mean nREPL ;-) Maybe, still I'm
frustrated that the server/backend actually has a name that we've recycled
for the client. Since session carries extra meaning with nREPL using it
is not an option.


Reply to this email directly or view it on GitHubhttps://github.com//issues/375#issuecomment-25069323
.

@purcell

This comment has been minimized.

Copy link
Member

commented Sep 25, 2013

Yep, I would tend to agree with Alexander here. The situation might not be perfect, but nobody else seems to have enough of a problem with it that it's worth imposing breaking changes on all users of the package. I'd suggest that at this stage there is consensus that a renaming is undesirable.

backend seems like a reasonable term to use in the code to avoid confusion. And we needn't worry too much about splitting up the package until there are multiple broadly-compatible backends IMO.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Sep 25, 2013

Fair enough. I guess I'm most annoyed with the situation just because I spend a lot of time dealing with the code while most people are simply using it. Anyways, I'm done arguing about this.

@bbatsov bbatsov closed this Sep 25, 2013

@klang

This comment has been minimized.

Copy link
Contributor

commented Sep 25, 2013

@bbatsov .. I for one hope that your drive on the project will continue, regardless of the name. nrepl.el is the way to connect to nREPL and that is important for a lot of Clojure/Emacs users who never see the elisp code.

@purcell

This comment has been minimized.

Copy link
Member

commented Sep 25, 2013

I for one hope that your drive on the project will continue, regardless of the name.

👍 Thanks for all your work, @bbatsov!

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Sep 25, 2013

@klang I wouldn't worry about that much :-) I just like to get every detail right and hate inconsistencies and ambiguities in a code base.

@timvisher

This comment has been minimized.

Copy link

commented Sep 25, 2013

👍 @bbatsov

I really appreciate all the work you do.

@darth10

This comment has been minimized.

Copy link

commented Sep 25, 2013

Unfortunate that we couldn't agree with @bbatsov .
IMHO it's Bozhidar's awesome ELisp chops that make nrepl.el what it is, rather than the name 😄
Just putting this out there since nrepl.el has really improved since he's taken over. 👍

EDIT: Not nREPL! I meant nrepl.el.

@purcell

This comment has been minimized.

Copy link
Member

commented Oct 2, 2013

Yeah, I think clime, clint and clomp are my favourites. clime is a nice reference back to slime, while clint is the most fun.

@purcell

This comment has been minimized.

Copy link
Member

commented Oct 2, 2013

(Needless to say, the idea of a clint-reload function is almost irresistible.)

@alexander-yakushev

This comment has been minimized.

Copy link
Member

commented Oct 2, 2013

2 cents: cl[^o].+ associates with Common Lisp for me rather than Clojure.

@technomancy

This comment has been minimized.

Copy link
Contributor

commented Oct 3, 2013

If I were to do it over, I would write it such that nrepl.el only handled the specific nrepl protocol and the user-visible functions would live in a separate library. That way the interface to other tools like lein.el, ac-nrepl, and nrepl-discover could be much smaller and more clearly defined.

It could also help us move more functionality server-side in order to avoid making everyone doing editor-support reinvent the wheel, as described here: https://github.com/technomancy/nrepl-discover/blob/master/Proposal.md But I've mentioned this repeatedly and have had a difficult time getting anyone to even pay attention, so it could be that approach is either flawed or doesn't address pain points other people have when implementing nREPL tooling.

In any case I agree that names starting with "cl" make me think of Common Lisp instead of Clojure.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Oct 3, 2013

@technomancy Both points make a lot of sense. I'm 100% behind the that the functionality that's now implemented with embedded Clojure code should be off-loaded to the server. The current approach simply does not scale and makes hard to maintain backward compatibility and implement non-trivial interaction ops.

As far as the naming goes, I guess this leaves options like cider, clomp (though someone might say this reminds him/her of the CL Object metaprotocol :-) )

I've had some more ideas:

  • ice (Integration/Interaction/IDE for Clojure on Emacs)
  • rice (REPL + above)
  • nemo (nREPL Emacs modes)
  • nerd (nREPL Emacs REPL & Devtools)
@samaaron

This comment has been minimized.

Copy link
Contributor

commented Oct 3, 2013

nReaper

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Oct 16, 2013

@purcell I'm done with the package split and plan to do the renaming today. I wonder how should I proceed for the benefit of MELPA users. My plan is:

  • rename this repo to cider
  • create another repo called nrepl with a rename notice and the code for the new nrepl.el, that's only a nREPL client (that would keep the current repipe going and all the links to the old name active)
  • submit a new repice cider to MELPA, depending on nrepl

Packages like ac-nrepl, etc should continue to work without any changes. People using nrepl.el should obviously rename a few symbols in their configs, but that would be a one time deal. I could add deprecated aliases for the old config options, but I don't think that would be necessary.

How does this sound?

@purcell

This comment has been minimized.

Copy link
Member

commented Oct 16, 2013

Sounds broadly reasonable, but I'm not sure I'm sufficiently informed to say for sure. Would it make sense for you to outline the changes you've made so we can all understand what to expect before the packages break everyone's config? That way we'll all be in a position to offer help.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Oct 16, 2013

The changes I've made so far are all transparent - I've simply broken down the monolith nrepl.el into several parts - nrepl-client, nrepl-interaction, nrepl-repl, nrepl-eldoc, etc. I'll rename everything but nrepl-client to cider-something and release it as the cider package, which will depend on nrepl (nrepl-client). Basically users will just have to replace a few nrepl- prefices with cider- prefices and everything will work for them just as it always did.

Most people will see that an update of nrepl.el remove just about everything they used so far. They'll go to report an issue, see the new instructions, install the cider package and continue coding :-)

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Oct 16, 2013

Alternatively I can simply rename this repo to cider and leave all the old code in the old repo, so people won't notice anything. If they decide they won't updates, they'll install cider. The downside of this approach is that we won't be able to spin of nrepl-client.el out of cider for some time, but I guess hardly anyone cares about that.

@purcell

This comment has been minimized.

Copy link
Member

commented Oct 16, 2013

Sounds like the first plan would end up with nrepl and cider packages, whereas the second would end up with just cider initially, and then also nrepl-client later. The latter sounds a bit cleaner to me, but will obviously cause the nrepl package to disappear from MELPA. That's not a problem in itself, because I think most MELPA users also have Marmalade enabled, and so they can always get the nrepl package from there if they're not ready to update their configs.

@purcell

This comment has been minimized.

Copy link
Member

commented Oct 16, 2013

I also think the second plan would be less work for you.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Oct 16, 2013

Yeah, certainly. I guess I go with that option.

@purcell

This comment has been minimized.

Copy link
Member

commented Oct 16, 2013

Let me know when you're ready, and I'll replace th nrepl recipe with one for cider.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Oct 16, 2013

@purcell I'm ready. You can go ahead and swap the recipes.

@purcell

This comment has been minimized.

Copy link
Member

commented Oct 17, 2013

Of course, the issue I missed with that option is that it makes things difficult for packages which depended on nrepl. Ahem... so perhaps splitting out nrepl-client.el sooner rather than later would be good...

@purcell

This comment has been minimized.

Copy link
Member

commented Oct 17, 2013

Although of course nrepl.el itself has gone, so all those packages would at least need to be updated to use a different require...

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Oct 17, 2013

I have a little bit of slicing and dicing more to do with nrepl-client.el, but I hope to spin it out of cider pretty soon.

@bbatsov bbatsov closed this Oct 17, 2013

bbatsov referenced this issue Oct 17, 2013

@purcell

This comment has been minimized.

Copy link
Member

commented Oct 18, 2013

FWIW, we now track package renamings on MELPA, so the cider package page lists not only the packages which depend on cider, but also (separately) those which still depend on nrepl, e.g. lein.

@purcell

This comment has been minimized.

Copy link
Member

commented Oct 18, 2013

I've submitted pull requests with suggested changes for lein, slamhound, clojure-cheatsheet and midje-mode.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Oct 18, 2013

Fantastic!

@mperrotta

This comment has been minimized.

Copy link

commented Oct 20, 2013

Cider was on marmalade 2 days ago and now its gone?

@glenjamin

This comment has been minimized.

Copy link

commented Nov 18, 2013

Hi, I've just read up on the rename by catching up on this issue - when trying to hit the old github repo the user is redirected to the cider repo - but unless they knew about the rename beforehand it's a bit jarring.

Could a note be placed near the top of the readme with a short note about the rename, maybe with a link to this dicussion? I'm unsure whether that would be confusing to people who didn't know it was nrepl.el and whether that would outweigh people who were confused by the change.

@bbatsov

This comment has been minimized.

Copy link
Member Author

commented Nov 19, 2013

@glenjamin There's a big "formerly nrepl.el" at the very beginning of the README, so I guess most users will quickly grasp the gist of the situation.

@glenjamin

This comment has been minimized.

Copy link

commented Nov 19, 2013

It was unclear to me whether this was a fork or simply a rename, just adding something like

"nrepl.el was renamed to cider to reduce confusion with the nrepl protocol"

Would eliminate any ambiguity imo

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.