docs: Add a Jujutsu from first principles doc.

[PhilipMetzger]

This document is WIP.

This came up recently in Discord as a explanation was requested without referencing Git, which all our other documents do.

Rendered

I'll probably need help from @martinvonz and @ilyagr to expand on this.

[joyously]

Seeing

as there are always multiple people working on the same file(s) at the same time

made me think of AutoMerge and then Grace.

[ilyagr]

I appreciate the intent, but I'm not sure it's time to write this kind of document. I'm worried it'll pin us down to some principles that are either vague or so specific that it'll limit jj's ability to adjust what it is based on ideas we have in the future.

I understand the appeal of such a document, but I, at least personally, don't feel ready to write or judge one.

I don't think anything you said is particularly bad or wrong, and I appreciate you thinking about these things, but it doesn't feel right enough to me. Perhaps a document that looks less definite and more like a brainstorming session would work a bit better for me.

Again, I don't want to discourage you from thinking about these things, and this is just my opinion, but I'm having a hard time coming up with edits to this that make it feel right. Perhaps others will have clearer ideas or a different opinion.

[ilyagr]

Nits: missing "to", Mercurial does not snapshot anything automatically.

[PhilipMetzger]

This was mostly taken from my understanding from this message from Martin in Discord. As all other CLI parts definitely take the good parts from hg.

[ilyagr]

These principles are more or less consistent with what jj is now, but I'm not sure they are good enough to be stated as "core tenets" of jj. They are a bit vague and I'm worried it pins our down a bit too much. I also feel differently about them, e.g. I'm not sure I believe in "having as few states as possible" even though, all else being equal, fewer states is of course better than more. We might want to add more states at some points (e.g. tracked and untracked branches were added recently, we might want some concept of topics). We can never make it so that it's "fundamentally impossible' to lose work in your repository, and while I believe quite a bit in trying to make that hard, a large increase in convenience might be worth a potential footgun.

[PhilipMetzger]

These principles are more or less consistent with what jj is now, but I'm not sure they are good enough to be stated as "core tenets" of jj. They are a bit vague and I'm worried it pins our down a bit too much. I also feel differently about them, e.g. I'm not sure I believe in "having as few states as possible" even though, all else being equal, fewer states is of course better than more.

Fair enough, I do think that the native backend should strive to keep it that way.

We might want to add more states at some points (e.g. tracked and untracked branches were added recently, we might want some concept of topics).

Here I tend do disagree with you, the whole tracked/untracked branch state only got introduced for Git interop, which isn't a concern for this doc. And topics are pure commit metadata, not another state, the main change will be in the clients.

We can never make it so that it's "fundamentally impossible' to lose work in your repository, and while I believe quite a bit in trying to make that hard, a large increase in convenience might be worth a potential footgun.

While that is true, some backend implementations can make if fundamentally impossible, e.g the Google Spanner one. So this is should be a implementation detail which isn't surfaced on the CLI. So we won't trade convenience there.

[ilyagr]

This is tangentially related, but it sounds to me that one of your goals here is to describe what JJ would look like without a git backend. Perhaps we could make it clearer in the doc. We could rename all of it to "JJ without Git" or "JJ from First Principles (without Git)", or split out sections that apply more to the Git-backed jj or to Git-less jj. I think I missed that this was your focus when I was first looking this over.

BTW, I may sound a bit conflicted on this topic, so I'll write the following down: I absolutely agree that it is important that jj makes sense conceptually without Git, so this is very much worth thinking about. At the same time, I personally think that the git backend is an absolutely essential part of jj and will continue to be so for years while people hopefully adopt it. So, I'm quite interested in jj being a better Git than Git to the degree possible. However, I don't think everyone agrees with assigning that much importance to the Git backend, and I also hope that it will slowly become less essential (though I do imagine this change to be slow for a while).

[martinvonz]

it sounds to me that one of your goals here is to describe what JJ would look like without a git backend.

Oh, I had not gotten that impression. I thought this doc was intended to explain jj to people who have no VCS background. If one of the goals is indeed to explain how it would look without the git backend, then I agree that that should be made clear.

[PhilipMetzger]

This is tangentially related, but it sounds to me that one of your goals here is to describe what JJ would look like without a git backend. Perhaps we could make it clearer in the doc. We could rename all of it to "JJ without Git" or "JJ from First Principles (without Git)", or split out sections that apply more to the Git-backed jj or to Git-less jj.

Yes, that's correct, so I've adjusted the title to your second suggestion.

Oh, I had not gotten that impression. I thought this doc was intended to explain jj to people who have no VCS background.

I would call that a that doc a Introduction to JJ. To my understanding a from first principles doc tries to explain the core concepts and goals of the project.

[steveklabnik]

I would consider moving this sentence to near the top, as one of the very first ones. And possibly change it to something like

The initial base design is to be a conceptually simpler Mercurial, without losing any of the powerful features DVCSes like Mercurial and Git have.

A lot of git folks worry a lot that "simpler" means "I can't do what I need to do," and also think already that Mercurial is a simpler git, so this would help address that.

Just my two cents though :)

[PhilipMetzger]

Thanks for the great suggestion.

A lot of git folks worry a lot that "simpler" means "I can't do what I need to do," and also think already that Mercurial is a simpler git, so this would help address that.

That's another great point, although I'm trying to avoid any references to Git as it is written from a pure Jujutsu PoV.

[steveklabnik]

I agree that being from a pure jujutsu POV makes sense, but you're already referencing Mercurial in this sentence, so I figured it was okay. :D

[martinvonz]

it sounds to me that one of your goals here is to describe what JJ would look like without a git backend.

Oh, I had not gotten that impression. I thought this doc was intended to explain jj to people who have no VCS background. If one of the goals is indeed to explain how it would look without the git backend, then I agree that that should be made clear.

[martinvonz]

I know what you're saying, but I think it's not technically correct (your PC can always crash before you even save, for example) and I think it's going to annoy some readers for that reason.

[PhilipMetzger]

I've rephrased it to be a bit weaker now.