Differences between revisions 17 and 19 (spanning 2 versions)
Revision 17 as of 2015-06-04 21:45:33
Size: 9278
Comment:
Revision 19 as of 2015-06-04 23:04:16
Size: 8974
Editor: AugieFackler
Comment:
Deletions are marked like this. Additions are marked like this.
Line 7: Line 7:
A plan for light weight branching/categorization what would work with other Mercurial principle and actual DVCS idea.

Still a very early prototype stage.
A (speculative) plan for topic branching that would work more seamlessly with common Mercurial workflows. Still very early prototype stage. Everything is subject to change.
Line 13: Line 11:
== Background == == Problem Statement ==
Line 15: Line 13:
Mercurial have been struggling for year to define a nice way to handle 'topic' branch (also called 'feature' branch) especially when it come to exchange them with other people (eg: for pull request). The Mercurial community has been struggling for years to define a nice way to handle 'topic' branches (sometimes also called 'feature' branches), especially when it comes to sharing them with other people (mainly for code review or other collaboration.)
Line 17: Line 15:
=== Constraint === Bookmarks are a clone of git's refs, which seems to work more poorly in Mercurial than they do in Git, in part because the synchronization parts of bookmarks aren't really done. Adding the remaining bits of git's refs to Mercurial has been controversial, and may represent enough of a behavior change that it's infeasible.
Line 19: Line 17:
The main challenges to get such feature right are: Named branches are visible forever in the revision history, which makes them unsuitable for feature branch work as the feature branch names rapidly pollute the output of things like `hg branches`.

=== Goals ===

The main challenges to get such a feature right are:
Line 22: Line 24:
  grouping/naming the topic branch is usually only relevant while working to get the feature done. We need a natural/efficient way for the topic to fade away when feature are complete. [augie notes that it might be interesting/useful to be able to query the topic name after the topic is done]   Grouping changes and naming the topic branch is usually only relevant while working to get the feature done. We need a natural/efficient way for the topic to fade away when feature are complete. [augie notes that it might be interesting/useful to be able to query the topic name after the topic is done]
Line 24: Line 26:
- '''Distributed system''':
  Mercurial lets an arbitrary number of changesets to interact with each other the way they want, include pulling changesets through a chain or repository. A good solution for topic branch should work well in such distributed environment. So topic information must be exchanged at the same time as the commit they are attached to.

- '''Tracking/Target''':
  People make changes with the goal to get them integrated into a main line of development (default, stable, version 4.2, stagging, etc). This "target" should be the default destination for merge, rebase, update (and any other command it make sense?). This aspect can probably use (or maybe need) integration with the life cycle.
- '''Distributed''':
  A good solution for topic branch should work well in a distributed environment, where users may be pulling from each other in arbitrary ways. Topic information must be exchanged at the same time as the commits they reference.
Line 31: Line 30:
  A topic is usually composed of multiple changesets, being able to easily define what is in the set is important for commands that handle topic as a whole (eg histedit, prev, next) and will probably be a very important point to design a good UI around evolve. Having a defined set of changesets is also needed when only part of the topic is exchanged (pushed or pulled). Topics cannot cannot just be defined from topological branch because rebasing a topic on the main branch makes such topological branch disappear (and also, topic may be multi headed or some topics share some common part of a branch).   A topic is usually composed of multiple changesets. Being able to easily define what is in the set is important for commands that handle topics as a whole (eg histedit and email.) Having a good mechanism for this will probably help produce a better UI in evolution as well. Having a defined set of changesets is also needed when only part of the topic is pushed or pulled. A topic for a change can't be derived from its topological branch and a bookmark because sometimes topics share a root, and sometimes exploration leads to multiple heads on a topic. [TODO(marmoute: work with augie to explain this sentence) It can also be confusing when a topic is rebased.]
Line 34: Line 33:
  Anonymous branch (and others graph property) is a useful feature of mercurial that adds flexibility and improve productivity. We should keep this strength available within each topic.   Anonymous branches is a useful feature of Mercurial that adds flexibility and improves productivity. We should keep this strength available within each topic.
Line 39: Line 38:
=== Goals Under Debate ===

- '''Tracking/Target''':
  People typically make changes with the goal of getting them integrated into a specific line of development (default, stable, version 4.2, staging, etc). This "target" should be the default destination for merge, rebase, update, etc. This aspect can probably use (or maybe need) integration with the life cycle.

    ''augie notes that he doesn't like the conceptual complexity this introduces''
Line 42: Line 48:
This section (and page) is not meant as "bookmarks are doomed, lets do something else." The idea here is "we have long standing issues with bookmark, lets think again from scratch a see what emerge." We'll see what to do with the other idea later. It's entirely possible that bookmarks can grow bits of new functionality and become topics. This plan is not meant as "bookmarks are doomed, lets do something else." The idea here is more driven by "we have some long standing issues with bookmarks, lets think again from scratch and see what emerges." We'll reconcile topics with bookmarks at a later date, once we know what we want. It's entirely possible that bookmarks can grow bits of new functionality and become topics.
Line 44: Line 50:
There is currently an experimentation around the idea of "remote bookmarks" and wider work flow changes, it will be "evaluated" independently. (its a wiki Feel free to update content of this section) There is currently an experimentation around the idea of "remote bookmarks" [TODO(augie): link to a remote bookmarks wiki page] and wider workflow changes, it will be "evaluated" independently. (it's a wiki, please feel free to update the content of this section)
Line 49: Line 55:
||tracking || || good ||
Line 53: Line 58:
||conflict || okay || good || ||conflict || okay || okay ||
||tracking || bad ||
good ||
Line 55: Line 61:
The lifecycle of bookmarks is problematic because we still have not figured out a good way to handle deletion and renaming. Once in the wild, it is very hard to get rid of a feature related bookmark. [augie and marmoute are not sure if remote-bookmarks improves that.]
Line 56: Line 63:
'''Life cycle''' of bookmark are problematic because we still have not figured out a good way to handle deletion and renaming. So once they are in the wild, it is very hard to get rid of a feature related bookmark. [augie and marmoute are not sure if remote-bookmarks improve that.] Behavior in '''distributed''' is okay-ish for the in-core bookmark. The current behavior on pull works in a distributed way: it will exchange any bookmark along with the matching changeset. Behavior on push is problematic as the local bookmark may not be pushed (Mercurial may warn about it, but this is not reliable.)
Line 58: Line 65:
Behavior in '''distributed''' is okay-ish for the in-core bookmark. The current behavior on pull work in a distributed ways as it will exchange any bookmark alongside their changeset. However behavior on push is more problematic as local bookmark may not be pushed, and Mercurial may warn about it or not depending unrelated condition. The 'remote-boomarks' change is more problematic in this aspect as remote name are not propagated so changesets can get exchanged without there topic information. [TODO(marmoute): work with augie to clarify this sentence] The 'remote-boomarks' change is more problematic in this aspect as remote name are not propagated so changesets can get exchanged without there topic information.
Line 60: Line 67:
'''tracking''' is not covered at all by current core version. It is introduced with 'remote-bookmark' but only cover rebase, the UI to setup and observe tracking is unclear to [marmoute] yet. '''tracking''' is not covered at all by current core version. It is introduced with 'remote-bookmark' but only covers rebase. Additionally, the UI to configure and observe tracking is unclear to [marmoute] yet.
Line 64: Line 71:
 * Requires the use of bookmarks for the main branches too.
 * Misbehaves if a some part of the topic is shared with another bookmark (or anon heads)
 * Bad handling of extra anonymous heads on the same topic.
 * ill defined behavior when push only half of a topic (who does not hold the bookmark)
 * Requires the use of bookmarks for the main branches
 * Misbehaves if a some part of the topic is shared with another bookmark
 * No way of handling of extra anonymous heads on the same topic
Line 69: Line 75:
Because they refer to a single changeset at the top of the stack, bookmark are bad at '''partial exchange'''. It is often practical to push or to pull only a part of the topic because the rest is not ready yet. Because the bookmark have no "start" the changesets are pulled anonymously in this case. Because they refer to a single changeset at the top of the stack, bookmark are bad at '''partial exchange'''. It is often practical to push or to pull only a part of the topic because the rest is not ready yet. Because the bookmark have no "start" the shared changesets are pulled anonymously in this case.
Line 71: Line 77:
For the same reason (refer to a single things) bookmark are does not allow for experimental branch and small popping heads in the same topics. For the same reason (referring to a single revision), bookmarks do not allow for experimental branches within a topic label.
Line 73: Line 79:
Beside the current state of their implementation, divergent bookmarks provide a solution for '''conflict'''. however it does not handle recessing a bookmark or deletion/recreation cycle, but this is more related to live cycle. Divergent bookmarks provide a solution for '''conflict'''. However it does not handle rewinding a bookmark or deletion/recreation cycles.
Line 79: Line 85:
 * Topic could be a property attached to each changesets (grouping them by similar topic)  * Topic could be a property attached to each changeset (grouping them by similar topic)
Line 90: Line 96:
 * Topic could be non contiguous ([[mpm]] idea) feature-foo -> fix-bar -> feature-foo. Allowing a stream lined work that is automatically split apart after that.  * Topics could be non contiguous ([[mpm]] idea) feature-foo -> fix-bar -> feature-foo. Allowing a streamlined work that is automatically split apart after that.
Line 92: Line 98:
 * Topic could be hierarchical 'issue4700.test' 'issue4700.preparation', activation//reference could be done at any level 'issue4700' or 'issue4700' (this could help handle branching/different approach)  * Topics could be hierarchical 'issue4700.test' 'issue4700.preparation', activation//reference could be done at any level 'issue4700' or 'issue4700' (this could help handle branching/different approach)
Line 103: Line 109:
== principle of very primitive extension == == Current Implementation ==
Line 105: Line 111:
Assign topics to non-public changesets. A topic is like a named branch, in that it is a label on a changeset (the initial prototype even stores the topic in the extra area in the changeset), but that topics just disappear when the change moves to public phase. Assign topics to non-public changesets. A topic is like a named branch, in that it is a label stored in a changeset's extra, but that topics just disappear when the change moves to public phase (the data still exists, it's just not shown.)
Line 107: Line 113:
== Problem solved == ==== Non-Goals ====
Line 109: Line 115:
=== What Topic solves ===  * Topics are not suitable for long term branches. We have named branches for that (and possibly also bookmarks, depending on workflow.)
Line 111: Line 117:
Bookmarks are a clone of git's refs, which seems to work more poorly in Mercurial than they do in Git, in part because the synchronization parts of bookmarks aren't really done. Adding the remaining functionality to bookmarks has been challenging, and seems to be adding a lot of conceptual complexity around configuration of the synchronization mechanism that AugieFackler finds frustrating. (<- This should be dispatched in the section related to bookmark).  * Topics are not suitable for tracking a moving point in public history. This seems to be a perfect fit for bookmarks.
Line 113: Line 119:
The current implementation also makes it possible to say "what patches did I do while working on topic `issue1234`", which might be nice.
Line 115: Line 120:
=== What Topic may solve === === Open Questions ===
Line 117: Line 122:
(Use case that exists but it is not clear if Topic should try to solve them)

=== What Topic do not solve ===

 * Topic seems orthogonal to tracking content of remote repository.

 * Topic is not fitted for long term branch, we have named branch for that (and bookmark?)

 * Topic is not fitted to track a moving point in public history (eg: devel vs stagging vs prod). Named branch are somewhat suitable but have their own issue, bookmark may be good to.

(Use case we know belong to other feature)

== Open Question ==

 * Right now we use changeset extra for storing the topic. That might lead to bonus divergence problems.
 * Right now we use changeset extra for storing the topic. That might lead to bonus divergence problems. They might be easily fixed, but should we avoid that?

Note:

This page is primarily intended for developers of Mercurial.

Topic Plan

A (speculative) plan for topic branching that would work more seamlessly with common Mercurial workflows. Still very early prototype stage. Everything is subject to change.

1. Problem Statement

The Mercurial community has been struggling for years to define a nice way to handle 'topic' branches (sometimes also called 'feature' branches), especially when it comes to sharing them with other people (mainly for code review or other collaboration.)

Bookmarks are a clone of git's refs, which seems to work more poorly in Mercurial than they do in Git, in part because the synchronization parts of bookmarks aren't really done. Adding the remaining bits of git's refs to Mercurial has been controversial, and may represent enough of a behavior change that it's infeasible.

Named branches are visible forever in the revision history, which makes them unsuitable for feature branch work as the feature branch names rapidly pollute the output of things like hg branches.

1.1. Goals

The main challenges to get such a feature right are:

- Life cycle:

  • Grouping changes and naming the topic branch is usually only relevant while working to get the feature done. We need a natural/efficient way for the topic to fade away when feature are complete. [augie notes that it might be interesting/useful to be able to query the topic name after the topic is done]

- Distributed:

  • A good solution for topic branch should work well in a distributed environment, where users may be pulling from each other in arbitrary ways. Topic information must be exchanged at the same time as the commits they reference.

- Clearly defined set of changes:

  • A topic is usually composed of multiple changesets. Being able to easily define what is in the set is important for commands that handle topics as a whole (eg histedit and email.) Having a good mechanism for this will probably help produce a better UI in evolution as well. Having a defined set of changesets is also needed when only part of the topic is pushed or pulled. A topic for a change can't be derived from its topological branch and a bookmark because sometimes topics share a root, and sometimes exploration leads to multiple heads on a topic. [TODO(marmoute: work with augie to explain this sentence) It can also be confusing when a topic is rebased.]

- Anonymous branching:

  • Anonymous branches is a useful feature of Mercurial that adds flexibility and improves productivity. We should keep this strength available within each topic.

- name conflict handling:

  • Fixing a bad name (or people fighting over a name) should not result in a very complicated situation (particularly around divergence.)

1.2. Goals Under Debate

- Tracking/Target:

  • People typically make changes with the goal of getting them integrated into a specific line of development (default, stable, version 4.2, staging, etc). This "target" should be the default destination for merge, rebase, update, etc. This aspect can probably use (or maybe need) integration with the life cycle.
    • augie notes that he doesn't like the conceptual complexity this introduces

1.3. Current shortcomings of bookmarks

This plan is not meant as "bookmarks are doomed, lets do something else." The idea here is more driven by "we have some long standing issues with bookmarks, lets think again from scratch and see what emerges." We'll reconcile topics with bookmarks at a later date, once we know what we want. It's entirely possible that bookmarks can grow bits of new functionality and become topics.

There is currently an experimentation around the idea of "remote bookmarks" [TODO(augie): link to a remote bookmarks wiki page] and wider workflow changes, it will be "evaluated" independently. (it's a wiki, please feel free to update the content of this section)

requirements

in-core

remote

Life cycle

poor

poor

distributed

okay

bad

defined set

poor

poor

partial exch

bad

okay

branching

bad

bad

conflict

okay

okay

tracking

bad

good

The lifecycle of bookmarks is problematic because we still have not figured out a good way to handle deletion and renaming. Once in the wild, it is very hard to get rid of a feature related bookmark. [augie and marmoute are not sure if remote-bookmarks improves that.]

Behavior in distributed is okay-ish for the in-core bookmark. The current behavior on pull works in a distributed way: it will exchange any bookmark along with the matching changeset. Behavior on push is problematic as the local bookmark may not be pushed (Mercurial may warn about it, but this is not reliable.)

[TODO(marmoute): work with augie to clarify this sentence] The 'remote-boomarks' change is more problematic in this aspect as remote name are not propagated so changesets can get exchanged without there topic information.

tracking is not covered at all by current core version. It is introduced with 'remote-bookmark' but only covers rebase. Additionally, the UI to configure and observe tracking is unclear to [marmoute] yet.

A bookmark can implicitly define a set of revisions since everything 'only' under that bookmark it can be considered in the topic. This has issues:

  • Requires the use of bookmarks for the main branches
  • Misbehaves if a some part of the topic is shared with another bookmark
  • No way of handling of extra anonymous heads on the same topic

Because they refer to a single changeset at the top of the stack, bookmark are bad at partial exchange. It is often practical to push or to pull only a part of the topic because the rest is not ready yet. Because the bookmark have no "start" the shared changesets are pulled anonymously in this case.

For the same reason (referring to a single revision), bookmarks do not allow for experimental branches within a topic label.

Divergent bookmarks provide a solution for conflict. However it does not handle rewinding a bookmark or deletion/recreation cycles.

2. Open idea

This is a list of idea that emerged while brain storming.

  • Topic could be a property attached to each changeset (grouping them by similar topic)
  • Topic could fade away when changesets become public (either archived or plain dropped)
    • A benefit of archiving them is that users can query for topics, eg you could say hg log -r topic(issue123) which would help

  • Tracking could be achieved through the naming scheme. eg:
    • 'default//feature-foo' would be a topic 'feature-foo' tracking the 'default' branch.
    • 'stable//issue4700' would be a topic 'issue4700' tracking branch stable.
    • '@//feature-bar' would be a topic 'feature-bar' tracking bookmark '@' ?
    • 'stable//issue4689//issue4700' would be a topic 'issue4700' tracking the topic 'stable//issue4689'. When topic 'issue4686' face away (because published), the tracking fallback to 'stable'.
  • Topics could be non contiguous (mpm idea) feature-foo -> fix-bar -> feature-foo. Allowing a streamlined work that is automatically split apart after that.

  • Topics could be hierarchical 'issue4700.test' 'issue4700.preparation', activation//reference could be done at any level 'issue4700' or 'issue4700' (this could help handle branching/different approach)
  • pushing a new head on a new topic to a non-publishing server would be allowed.

    • that is, it'd be legal to have one head per topic on a non-publishing server.
  • A changeset could maybe have multiple topic.
    • Augie doesn't feel great about this option just because of UI complexity.
  • Users can name patches (in a sense) without mq
    • One of the major complaints about evolve from veteran mq users is that their patches no longer have explicit names. Topics provide a potential way to name patches again.

3. Current Implementation

Assign topics to non-public changesets. A topic is like a named branch, in that it is a label stored in a changeset's extra, but that topics just disappear when the change moves to public phase (the data still exists, it's just not shown.)

3.0.1. Non-Goals

  • Topics are not suitable for long term branches. We have named branches for that (and possibly also bookmarks, depending on workflow.)
  • Topics are not suitable for tracking a moving point in public history. This seems to be a perfect fit for bookmarks.

3.1. Open Questions

  • Right now we use changeset extra for storing the topic. That might lead to bonus divergence problems. They might be easily fixed, but should we avoid that?
  • Should changesets be allowed multiple topics?
  • How permissive should we be on topic names?


CategoryDeveloper and CategoryNewFeatures

TopicPlan (last edited 2021-10-08 14:11:59 by GeorgesRacinet)