Differences between revisions 1 and 25 (spanning 24 versions)
Revision 1 as of 2015-05-21 03:26:01
Size: 619
Comment:
Revision 25 as of 2015-10-23 16:21:51
Size: 6650
Comment: added data about behavior regarding branch name.
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
#pragma section-numbers 2
Line 3: Line 5:
A plan for light weight branching/categorization what would work with other Mercurial principle and actual DVCS idea. = Topic Plan =
Line 5: Line 7:
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 9: Line 11:
== Principle == == Problem Statement ==
Line 11: Line 13:
assign topics to non-public changesets 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 13: Line 15:
== Problem solved == 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 15: Line 17:
=== What Topic solve === 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`.
Line 17: Line 19:
(Use case Topic target to address) == Current Target ==
Line 19: Line 21:
=== What Topic may solve === This describe the target semantic and behavior for topics.
Line 21: Line 23:
(Use case that exists but it is not clear if Topic should try to solve them) === General semantics ===
Line 23: Line 25:
=== What Topic do not solve === TL;DR; topic are an extra "light-branch" data relevant to draft changesets.
Line 25: Line 27:
(Use case we know belong to other feature)  * Topic is a ''name'' explicitly attached to changesets,
Line 27: Line 29:
== Principe ==  * This Topic data is primarily meant to categorize ''draft changeset'' and fade out when things become public,
Line 29: Line 31:
 * Changeset have both a ''topic'' and a 'branch'. The ''topic'' allow to gather related in progress work, while the ''branch'' data refer to the long terms line of development.

 * Behaviors focus on ensuring any ''name'' have a single head.

 * Behaviors related to named branches behave mostly as if the draft-with topic are not on the branch (yet).

 * Behaviors within a topic are similar (with minor sensible difference) to named branches one within the topic.

=== General effect on named branch ===

Changeset with topic are ''only aspiring'' to be part of the named branch, but not fully in that branch yet. when you have branch `foo` name `foo` is resolved to the heads of `foo` with no topic.

Three is a couple of examples:

{{{#!dot
digraph {
  rankdir=LR
  node [shape=box,style=filled]
  A -> B -> C;
  B -> X -> Y;
  A [label="A\n(b: foo)"];
  B [label="B\n(b: foo)"];
  C [label="C\n(b: foo)"];
  X [label="X\n(b: foo)\n(t: bar)",fillcolor="lightblue"];
  Y [label="Y\n(b: foo)\n(t: bar)",fillcolor="lightblue"];
}
}}}

Multiple heads are not longer ambiguous,

 * The name `foo` resolve to C,
 * The name `bar` resolve to Y,

----

{{{#!dot
digraph {
  rankdir=LR
  node [shape=box,style=filled]
  A -> B;
  B -> X -> Y;
  A [label="A\n(b: foo)"];
  B [label="B\n(b: foo)"];
  X [label="X\n(b: foo)\n(t: bar)",fillcolor="lightblue"];
  Y [label="Y\n(b: foo)\n(t: bar)",fillcolor="lightblue"];
}
}}}

Partial data does not have radical change on the definition,

 * The name `foo` resolve to B,
 * The name `var` resolve to Y,

----

{{{#!dot
digraph {
  rankdir=LR
  node [shape=box,style=filled]
  A -> X -> B;
  A [label="A\n(b: foo)"];
  X [label="X\n(b: foo)\n(t: bar)",fillcolor="lightblue"];
  B [label="B\n(b: foo)"];
}
}}}

Usual traversal rules apply:

 * The name `foo` resolve to B,
 * The name `var` resolve to X,

=== Behavior for update ===

This implies change in hg update behavior (but are not super relevant)

=== Behavior for merge ===

This assume `hg rebase` and `hg merge` to be identical

=== Behavior for push to publishing (default repo) ===

=== Behavior for push to non-publisehd repo ===

=== Stacked diffs workflow ===

=== User Transition ===

== Pro and Cons ==

== Other questions ==

== Open ideas ==

This is a list of idea that emerged while brainstorming. This served as base for the current things.

 * 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.

== 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.)

Code is available at [[http://hg.durin42.com/hg-topic-experiment/]].

==== 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.


=== 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?

== See also ==

 * FeatureBranchesStruggle

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.

2. Current Target

This describe the target semantic and behavior for topics.

2.1. General semantics

TL;DR; topic are an extra "light-branch" data relevant to draft changesets.

  • Topic is a name explicitly attached to changesets,

  • This Topic data is primarily meant to categorize draft changeset and fade out when things become public,

  • Changeset have both a topic and a 'branch'. The topic allow to gather related in progress work, while the branch data refer to the long terms line of development.

  • Behaviors focus on ensuring any name have a single head.

  • Behaviors related to named branches behave mostly as if the draft-with topic are not on the branch (yet).
  • Behaviors within a topic are similar (with minor sensible difference) to named branches one within the topic.

2.2. General effect on named branch

Changeset with topic are only aspiring to be part of the named branch, but not fully in that branch yet. when you have branch foo name foo is resolved to the heads of foo with no topic.

Three is a couple of examples:

Multiple heads are not longer ambiguous,

  • The name foo resolve to C,

  • The name bar resolve to Y,


Partial data does not have radical change on the definition,

  • The name foo resolve to B,

  • The name var resolve to Y,


Usual traversal rules apply:

  • The name foo resolve to B,

  • The name var resolve to X,

2.3. Behavior for update

This implies change in hg update behavior (but are not super relevant)

2.4. Behavior for merge

This assume hg rebase and hg merge to be identical

2.5. Behavior for push to publishing (default repo)

2.6. Behavior for push to non-publisehd repo

2.7. Stacked diffs workflow

2.8. User Transition

3. Pro and Cons

4. Other questions

5. Open ideas

This is a list of idea that emerged while brainstorming. This served as base for the current things.

  • 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.

6. 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.)

Code is available at http://hg.durin42.com/hg-topic-experiment/.

6.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.

6.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?

7. See also


CategoryDeveloper and CategoryNewFeatures

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