|
Size: 3600
Comment:
|
Size: 3910
Comment: move some content to Feature Branches Struggles
|
| 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: |
| == Background == | == Problem Statement == |
| Line 11: | 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 13: | 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 15: | 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`. |
| Line 17: | Line 19: |
| - '''Life cycle''': 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. |
== Open ideas == |
| Line 20: | Line 21: |
| - '''Distributed system''': Mercurial let 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. |
This is a list of idea that emerged while brainstorming. |
| Line 23: | Line 23: |
| - '''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. |
* Topic could be a property attached to each changeset (grouping them by similar topic) |
| Line 26: | Line 25: |
| - '''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 topic as a whole (eg histedit, prev, next) and probably a very important point to design UI around evolve. Having a defined set of changesets is also needed when only part of the topic is exchanged (pushed or pulled). Topic 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 topic share some common part of a branch). |
* 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 |
| Line 29: | Line 28: |
| - '''anonymous branching''': Anonymous branch (and others graph property) is a useful feature of mercurial that adds flexibility and improve productivity. We should keep this strength. |
* 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'. |
| Line 32: | Line 34: |
| == Principle == | * 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 34: | Line 36: |
| 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. | * 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 36: | Line 38: |
| == Problem solved == | * 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. |
| Line 38: | Line 41: |
| === What Topic solves === | * A changeset could maybe have multiple topic. * Augie doesn't feel great about this option just because of UI complexity. |
| Line 40: | Line 44: |
| 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. | * 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. |
| Line 42: | Line 47: |
| The current implementation also makes it possible to say "what patches did I do while working on topic `issue1234`", which might be nice. | == Current Implementation == |
| Line 44: | Line 49: |
| === What Topic may solve === | 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 46: | Line 51: |
| (Use case that exists but it is not clear if Topic should try to solve them) | Code is available at [[http://hg.durin42.com/hg-topic-experiment/]]. |
| Line 48: | Line 53: |
| === What Topic do not solve === | ==== Non-Goals ==== |
| Line 50: | Line 55: |
| (Use case we know belong to other feature) | * Topics are not suitable for long term branches. We have named branches for that (and possibly also bookmarks, depending on workflow.) |
| Line 52: | Line 57: |
| == Open Question == | * Topics are not suitable for tracking a moving point in public history. This seems to be a perfect fit for bookmarks. |
| Line 54: | Line 59: |
| * Right now we use changeset extra for storing the topic. That might lead to bonus divergence problems. | === 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? |
| Line 58: | Line 66: |
| == 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. Open ideas
This is a list of idea that emerged while brainstorming.
- 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.)
Code is available at http://hg.durin42.com/hg-topic-experiment/.
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?