Topics Roadmap

This page contains status of various things related to the topic extension.

1. Topics

The topic extension contains two related concepts, topic and stack.

The topic concept focus on solving the Feature Branch problem. Its goal is to help identify and exchanges draft that belongs to short lived feature branch. It focus on being lightweight to use with a simple and clear life cycle.

The stack concept focus on providing a good interface to deal with a stack of patches. If topic concept helps to defines the current set of changeset related to your current work, the stack concept helps to actually do work on the stack. The focus is on simplifying visualization, edition and movement within the stack. It also introduces ways to smooth some of the changeset evolution concepts.

The stack concept does not depends on the topic concept. Anything able to define a stack could reuse the work done around the stack concept.

• a feature we have working

• a feature we "sort of" have

• a feature we still miss but want to have

• a question about possible feature or behavior (usually have some tricky bits)

2. Goal of the Topic concept

Topic primary goal is to solve the feature branch struggle.

• It defines a set of changeset that belong to a feature branch.

  we can easily select all changesets on a topic.

• It provides consistent "naming" experience:

  <topic-name> match the tipmost changeset on the topic as for branch.

  <branch-name> excludes changeset with topic.

  maybe the name should match the semantic head (post evolve head) instead of just the tip most changeset.

• It must have a clear clear life cycle:

  topic fade away when changeset are published.

  what would be the local workflow to "merge" a topic before publishing

• It open the way to a clearer "each name should have one head" world (but still allow multiple anonymous heads when their are handy)

  warn on multiple heads in hg topic --verbose

  config option to reject multiple heads on the a given topic (server side, per branch)

  better "created new head" message

  creating a new head on the branch, should suggest to use topic

  pushing new topic to non publishing server is allowed (without --force or --new branch)

  We can reject publishing of topic (on the server) if it makes a new heads to a branch

  update and merge destinations can stay limited to the active topic to keep them useful and predictable.

• offer a "natural" and simple "tracking" concept.The word "tracking" is borrowed to git vocabulary. It refer to the ability for a feature branch to known another "branch" it is targeted to be "merged" in. In the case of topic, we use the named branch of the changeset, since this is where the changeset will be once published. (This combine well, with the update to the semantic of branch head mentioned earlier in the "naming" section.)

  hg topic -v and hg stack show the "behind" count. This is the number of changesets on the tracked branch that has not been merged in (or rebased on) the current topic. (need to be documented so that user can understand it and also show the branch name).

  hg merge and hg rebase target the "tracked" branch by default. (the behaviour of merge/rebase above is a bit ambiguous compared to the "in-topic" merging, maybe we should do something better here)

• Help to organize concurrent work (solo or as a team):

  have an option to list topic (in hg topic) by "last touched" time and maybe author too.

  Multiple topics on the same changeset.

  Some kind of namespacing by users to help distinct your topic from other people topic.

• forbid commit without topic.

  an config option to turn this on or off

3. Goal of the Stack

Stack primary goal is to provide a smooth experience when working with a stack of commit.

The "stack" does not needs to be always linear at all time. Having multiple heads locally is sometimes practical for short while. Evolution will also allow creation of non-topological-linear stack (even is the "semantic" may stay linear)

We do not really care about what defines the stack. Right know we supports:

• topic

  named branch (non public part)

Overall we wants to be able to:

• easily view all changeset in the stack

  hg stack does this. It filter out obsolete changesets too

  display short node with --verbose

  template support to control the changeset display

• Not having the graph is a choice here. Since we want to encourage people to have a linear stack it make sense to optimize for the linear case (that does not need a graph, it is linear!).

  have a --graph option for when it is useful.

  the list order is strange when the topic is not continuous,

  how do we display merge changeset in a topic.

• provides easy way to move within the stack:

  provide short and easy indexing (t#, should be based on '{}' indexing). This is pretty important. With these short hand, we can avoid the need for the user to copy-paste changeset nodes or revision numbers. This is significantly easier to use and less error prone.

  hg prev and hg next commands to go up and down in the stack.

  properly constrains these to within the stack,

  provide a "root" point as t0 (+ hg prev support),

  warn when the indexing is updated (transaction hooks),

• Smooth the complexity related to evolution. Some aspect of evolution can be a bit hairy when presented raw to the user. (This complexity comes from exchanging and rewriting draft changesets, not from evolution itself.)
  • There are multiple things we can leverage the stack concept to help here:

  Display the stack linearly "as-if-evolved".

  • This is very important as it give users, a "previous" of the evolution, making it predictable to them. In addition this hides some of the complexity of "orphan/unstable".

  Display "unstable/orphan" warning next to the changeset in the

  • stack.

  Handle and display divergence in a meaningful way

  should we display more data in --verbose more? (something like hg evolve --list)

  have hg next automatically evolve (currently with --evolve option, need some proper continue/abort mechanism before moving forward)

  Should we use in memory merges to warn about conflict directly in the output

  hg evolve --all is restricted to the topic, and the full topic. We probably need something "stack" based to trigger this.

  provide a good command set to edit the stack

• Quick access to essential information. If we focus the UI around stack it better to have important data about the stack easily accessible.

  • Warn on multiple (semantic heads)

    display troubles/instability in the stack

    display tracking information (behind)

4. Possible Road Map

Stack is quick valuable in many aspect, especially for the local usecase (fill the MQ usecase, simplify) so it would make senses to try to stabilize and upstream that first. In addition, nothing from stack involve any "format" changes or behavior changes in itself, so it seems simpler to start there.

4.1. Proof of concept stage

This is what is currently happening in the "topic" extension, in the hg-evolve repository.

The goal is to get the core behavior of both "stack" and "topic" up and running to be able to play with it and get wider feedback from various places with various workflow.

Adding other way to define stack other than topic is perfectly fine here.

4.2. Moving "stack" to core

We move it an experimental 'stack' extensions ("hgext/stack.py") first.

This involves at least:

a) the stack command and associated features, b) movement comment (next/prev, {'t#'}, etc) c) smooth, handling of orphan through (hg next)

Using named branch to define the stack by default seems fine since this is already available in core. Having topic plug into that logic to offer an definition for stack.

(We need to expand that plan a bit, but I would like to keep things simple for now.)

Hopefully, we could do that during the 4.4 cycle. We should also get involved with the Gregory Szorc work around hg show stack there seems to be synergy there.

4.3. Moving "topic" to core

There is a bit more discussion and exploration we need to do around topic, so we could focus on stack first. But then moving it into either the "stack" extension of its own "topic" extensions would be a good first step. Especially there is multiple awful hack in the current extension that would be easier to clean up closer to core.