cli: deprecate jj checkout and jj merge

[thoughtpolice]

As discussed on Discord and in previously in #1713, this deprecates jj checkout and jj merge, as they are simply specializations for existing functionality under jj new.

Both commands are now hidden by default from help.

Supersedes #1713.

Checklist

If applicable:

• I have updated CHANGELOG.md
• I have updated the documentation (README.md, docs/, demos/)
• I have added tests to cover my changes

[martinvonz]

I chose jj 0.18.0 as the version to target for removal, as the next release is 0.14, and we do monthly releases, resulting in a four-month window. I think this is a fair amount of time, but I'm open to other suggestions if people want it to be longer or shorter.

I think we've aimed for at least 6 months before. I see little harm in giving users a bit longer. It's cheap to maintain, and users are probably not deliberately going to keep using the old commands if we warn every time as we do after this PR. What do you think?

[PhilipMetzger]

Thanks for finally doing finishing this :-). I've left some comments. A final question is what do we do with jj checkout's aliases, do they stay as convience aliases or are they just removed?
This was something we didn't decide on the last time the deprecation was brought up in Discord, IIRC ilya is a big user of jj co.

[thoughtpolice]

I think 6 months is fine, so I adjusted it the timeline in the CHANGELOG.

But I removed the exact notice of version in the error messages as Philip asked; it's only now mentioned in the changelog. I feel this is a good balance, since it's not something people will precisely beat us over the head with, it at least gives them an idea of when it will happen, and the actual deadline itself isn't too committal.

I'm not sure about adding a rationale to the actual message; I don't think making it too long helps. I'll think about it a tiny bit more.

[thoughtpolice]

A final question is what do we do with jj checkout's aliases, do they stay as convience aliases or are they just removed? This was something we didn't decide on the last time the deprecation was brought up in Discord, IIRC ilya is a big user of jj co.

We could remove them when the commands are actually turned into hard errors, allowing them to be reused; so that jj checkout is an error but jj co is free — which means Ilya would be able to re-purpose jj co again as an alias. That might be an OK tradeoff.

Right now, aliases cannot override any command even if it's a no-op. So we'd otherwise have to fix that.

[martinvonz]

Thanks!

[PhilipMetzger]

We could remove them when the commands are actually turned into hard errors, allowing them to be reused; so that jj checkout is an error but jj co is free — which means Ilya would be able to re-purpose jj co again as an alias. That might be an OK tradeoff.

Right now, aliases cannot override any command even if it's a no-op. So we'd otherwise have to fix that.

Basically #1713 (comment) and the following two messages seem a more appropriate approach. I think ATM moving the aliases to jj new makes sense and after actually removing jj checkout we can discuss the removal of the aliases.

My argument for the whole thing is that a CLI is basically a API, so the same concepts should apply.

And another thing which I only noticed now, why is it a warning instead of an hard error like #1911? I assume we will make them a hard error in a few releases, like #1911 did?

[Fraetor]

I've spotted two places in the documentation where checkout is mentioned.

• jj co main on the Git comparison page.
• jj checkout/co in the Tutorial.

[ilyagr]

Left some very minor and optional nits about the changelog.

I think this is a good change, hopefully other users will agree.

Please also fix the docs mentioned by @Fraetor.

[martinvonz]

This seems very close to done. Do you think you can find time to get this merged before I cut a new release next week?

[thoughtpolice]

This seems very close to done. Do you think you can find time to get this merged before I cut a new release next week?

Yeah, I should be able to do it tonight or this weekend I think.

[thoughtpolice]

I think I've addressed everyone's nits; however, I have still left the rationale in the changelog, and the reason is simple: because users read the changelog, but we read the history. It's simply friendlier to explain this deprecation there, in my opinion.

I have however made the actual changelog entry much shorter and more direct, and I've also put the more detailed rational in the commit messages themselves as requested. So I think this is a good end result all around.

[martinvonz]

Thanks!

[martinvonz]

I sent #2929 to unblock CI

[ilyagr]

(Non-blocking)

We could remove them when the commands are actually turned into hard errors, allowing them to be reused; so that jj checkout is an error but jj co is free — which means Ilya would be able to re-purpose jj co again as an alias. That might be an OK tradeoff.

I think I'd literally make them into default aliases in the built-in settings. Then, people can change them. But this is not important that we do so and it's a discussion for another time.

[thoughtpolice]

That's a good idea; we can still follow up on that in time for the release window, I think. But yes, I'll go ahead and merge this.

[matts1]

Was chatting with @martinvonz today about the warning we now show.

warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
warning: `jj checkout` will be removed in a future version, and this will be a hard error

jj checkout, jj amend, jj merge, and jj commit, while not actually required, all allow new jj users to think with their git-brain rather than having to come up with a whole new understanding of how jj works. I'm all for showing a message whenever you use these commands suggesting how to use things in what I'll call "jj-style", but personally I strongly advocate against removing jj checkout and similar commands, since I believe doing so will increase the barrier-to-entry of jj with no explicit benefits.

I think I'd literally make them into default aliases in the built-in settings. Then, people can change them.

This seems like a reasonable approach to me, though it does make it more difficult to tell users "have you considered jj new" when they try running jj checkout.

That being said, it did confuse an internal user when they wrote jj help amend and got documentation for squash. I think the approach I'd like is for them to be a default alias, and as a seperate feature request, when I run jj help <alias>, it would expand the alias first. Something like:

jj help checkout
Alias for jj new

Help for jj new:
<jj help new>

[ilyagr]

That being said, it did confuse an internal user when they wrote jj help amend and got documentation for squash. I think the approach I'd like is for them to be a default alias, and as a seperate feature request, when I run jj help , it would expand the alias first.

I did request the same thing in #2866 (comment). I'm guessing @jyn514 might be working on a simpler version of that feature first, though.

[PhilipMetzger]

Was chatting with @martinvonz today about the warning we now show.

warning: `jj checkout` is deprecated; use `jj new` instead, which is equivalent
warning: `jj checkout` will be removed in a future version, and this will be a hard error

jj checkout, jj amend, jj merge, and jj commit, while not actually required, all allow new jj users to think with their git-brain rather than having to come up with a whole new understanding of how jj works. I'm all for showing a message whenever you use these commands suggesting how to use things in what I'll call "jj-style", but personally I strongly advocate against removing jj checkout and similar commands, since I believe doing so will increase the barrier-to-entry of jj with no explicit benefits.

I am strongly against upholding the whole git shtick, as removing these commands makes jj unique and allows us to have some affordances on behalf of the users workflow. While Git is the dominant system for the forseeable future, it shouldn't prevent innovation and UI affordances like jj already has. Or do you also want to go back to manually jj adding files?

I also dislike that this concern was raised so late after we discussed the removal for so long.

[martinvonz]

While Git is the dominant system for the forseeable future, it shouldn't prevent innovation and UI affordances like jj already has.

I don't think keeping jj checkout and jj merge as almost-aliases for jj new really prevents any innovation, unless we feel like we want to use those command names for some new feature. The commands print a warning and point the user to jj new, so I think we're making it clear that we think there's a better way.

Or do you also want to go back to manually jj adding files?

That's #323. Let's keep this discussion focused on jj new/checkout/merge.

I also dislike that this concern was raised so late after we discussed the removal for so long.

Not all users are going to be part of our Discord and/or GitHub discussions, so they will not notice until they upgrade to a release with the new behavior.

[joyously]

To be complete: I don't think to use checkout, but hearing of it makes me think of SVN, even though I use Breezy with "lightweight checkout" branches.
As for merge, in Breezy it's for branches(which are the main focus), and there aren't really branches in jj (similar to Darcs) so I don't think of it.

[PhilipMetzger]

I don't think keeping jj checkout and jj merge as almost-aliases for jj new really prevents any innovation, unless we feel like we want to use those command names for some new feature. The commands print a warning and point the user to jj new, so I think we're making it clear that we think there's a better way.

My main point is being unique with not having these commands at all. The best moment to remove something is yesterday, today or not at all.

Or do you also want to go back to manually jj adding files?

That's #323. Let's keep this discussion focused on jj new/checkout/merge.

This was a purely rhetorical question, in terms of going back to the old ways because innovation shouldn't happen.

I also dislike that this concern was raised so late after we discussed the removal for so long.

Not all users are going to be part of our Discord and/or GitHub discussions, so they will not notice until they upgrade to a release with the new behavior.

Matt is atleast in the Discord, not a dogfooded user which I never heard of, so there should atleast be a better way to present internal feedback to OSS users instead of just backing out something with a unreasonable short explanation and response time.

[martinvonz]

there should atleast be a better way to present internal feedback to OSS users instead of just backing out something with a unreasonable short explanation and response time.

I tried to explain it in 97d1cb7. I'm sorry that it felt unreasonably short. What additional information would you have wanted me to include? Or maybe your objection is to using a PR for discussion? Oh, I should probably have included "RFD:" in the PR title? I'll update it.

[joyously]

Both of them seemed fast to me, especially the second one.
Was it based on that one internal user?
I am one user, and to me, checkout means svn checkout which gives you just a piece (one folder) of the repo or brz checkout which gives you a branch (which in Breezy is a folder).
I don't like how several VCS have used the same term differently, and adding one more is not that great an idea.

[martinvonz]

Was it based on that one internal user?

No, it was based on feedback I've heard from several people over many months.

I am one user, and to me, checkout means svn checkout which gives you just a piece (one folder) of the repo or brz checkout which gives you a branch (which in Breezy is a folder).
I don't like how several VCS have used the same term differently, and adding one more is not that great an idea.

I'm sorry, but I think you're an unusual user :) Most users come from Git, and Git does have a checkout that's very very similar to jj checkout.

[ilyagr]

I did request the same thing in #2866 (comment). I'm guessing @jyn514 might be working on a simpler version of that feature first, though.

Actually, there's already #3015 that can be looked at.