WIP: docs/design: Topics

[PhilipMetzger]

Continues the conversation started in Discord and hopefully concludes it with a final design.

Rendered

[PhilipMetzger]

Also cc @necauqua and @noahmayr since they were heavily involved in the first discussion.

[necauqua]

While this works it falls short of having the metadata synced by multiple clients, which is something desirable. The prototype thus also avoids rewriting the Change-ID which is a good thing, but makes them only locally available.

Uh, the part where this was discussed completely escaped me?. Why is "having the metadata synced by multiple clients" something desirable? I mean it surely would be nice, with an actuall jj remote that's yet to exist, but without that we have to resort to annoying and intrusive things like rewriting commit messages or similar.

I thought we were settled on them being locally available (like the oplog, for example) and for easy editing of topics without actually rewriting commits.

And for sharing them through a git remote, roundtripping through git branches - while only really works nice for single-head topics that branch off the trunk - is plenty imo.

Interoping with some gerrit features would be then the job of the gerrit integration etc.

[scott2000]

I have a few questions which don't seem to be answered yet in the design doc:

• Will jj bookmarks still be able to track remote git branches (meaning they'll be updated on fetch)?
  • If so, can a bookmark and a topic track the same remote git branch?
• Will jj bookmarks still be pushed as git branches?
• Will git branches still be fetched as jj remote bookmarks?
• Can git branches be fetched as topics even if they were created by someone else?
  • If so, how does jj know what the base branch is?
    • Is there a command to set the base branch for fetching a topic?
    • If it defaults to trunk(), is it impossible to fetch trunk() (or a branch that's an ancestor of trunk()) as a topic since there's zero commits in that range?
    • How does this work for projects with multiple long-lived branches?
• Is there such a thing as a "remote topic"?
  • If so, what determines whether a git branch is fetched as a remote bookmark or a remote topic?
  • Or are there only remote bookmarks still, and there's an explicit command to start tracking a remote bookmark as a local topic?
• Can a topic and a bookmark have the same name?
  • If so, which takes precedence? Do they have different syntax?
• Can a topic be conflicted?
  • If so, how are topic conflicts resolved?
• If there's a series of commits trunk(), A, B, C and I set a topic as B, C and push it, I assume the remote git branch will be pointing to C. What happens if a coworker rebases the branch, creating the new series of commits trunk(), X, A', B', C' with the remote git branch pointing to C' now? When I fetch, does my topic get expanded to X, A', B', C', or does it become B', C' somehow? Or does it become conflicted?

[PhilipMetzger]

I'm going to create threads for top-level questions, since GitHub's UI for them isn't great and I expect that this will receive more than a handful of comments. Since this is isn't nearly done yet.

[emesterhazy]

I think the doc needs to explain the details of how topics are propagated infectiously. What happens, for example, if I rebase a commit that belongs to a topic onto another topic (including the anonymous topic). Does it cease to be part of that topic, or do I end up with a single disjoint commit belonging to the original topic?

[PhilipMetzger]

I wanted to give an update on this thing, I have largely rewritten this doc in last 6 months but to me it's still not good enough to go out of the WIP state. I will update it soonish though.

[jennings]

@PhilipMetzger I think the most important thing to document is what topics are meant to accomplish. I think different people expect them to solve different problems, and it's not clear to me what we're trying to do.

For example, here are the goals as written in the current revision:

• Introduce the concept of native topological branches for Jujutsu.

Why do we want this concept? Doesn't this already exist just by nature of the commit graph being a DAG? We just don't name the branches, but why do we want to?

• Simplify Git interop by reducing the burden on Bookmarks.

What's painful about it? I think this is specifically to address advancing bookmarks, but we should explain the use case explicitly.

• Add Change metadata as a storage concept.

Why do we want to do this? Isn't this already handled by the new change-id header? (It's possible this simply predates the header and is no longer necessary)

• Remove the awkward bookmark to Git branch mapping.

What's awkward about it?

[PhilipMetzger]

Thanks for the feedback @jennings.

I think the most important thing to document is what topics are meant to accomplish.

Agreed, that always is/was the goal. It just happened to be that this design doc got attention in an incomplete state where I rolled with the punches which changed the contents. It (and I) never were ready for that so the state pretty much reflects that.

I think different people expect them to solve different problems, and it's not clear to me what we're trying to do.

I think there are at least five different versions of Topics floating around, where one is mine which made it onto a design doc others pretty much only exist as "vibes" in active discussions. Whether the project wants a design doc for it or just an implementation like #3419 is pretty much up to the community and the maintainers.

• Introduce the concept of native topological branches for Jujutsu.

Why do we want this concept? Doesn't this already exist just by nature of the commit graph being a DAG? We just don't name the branches, but why do we want to?

I think this is addressed in my local version, but I think the named part has been missing the whole time.

• Simplify Git interop by reducing the burden on Bookmarks.

What's painful about it? I think this is specifically to address advancing bookmarks, but we should explain the use case explicitly.

👍

• Add Change metadata as a storage concept.

Why do we want to do this? Isn't this already handled by the new change-id header? (It's possible this simply predates the header and is no longer necessary)

It is a separate thing I want, which is reconcilable with my ideal implementation, someone else probably could make Topics work without that since it then would only encompass 10% of the current design.

• Remove the awkward bookmark to Git branch mapping.

What's awkward about it?

The concepts don't match all in my opinion. Bookmarks give a name to a single change which doesn't really fit the expectations of Git branches.

I will push the revised v2 with your points addressed and open the discussion again but after that it's unlikely that I will spend further time on it, since the last months can be considered a waste.

Let me explain my motivations here, until about a year ago there were constant complaints that jj is to tedious to use for feature branches and long-living Git branches and that jj tug or its variants are inadequate. Topics should hopefully solve that, since it gives those users what they want. It definitely isn't my problem so I think another person which is affected by it should step up. Like I could punch this through (the willpower is here), but I am no longer motivated to do so.

Anyway, I've recently realized that my time as a contributor and community member in the project has an expiry date which is likely sooner rather than later.