/!\ This page is primarily intended for Mercurial's developers.

/!\ This page is no longer relevant but is kept for historical purposes.

Patch handling unification IRC logs and ideas

This is a wiki page to try to summarize ongoing IRC chatlogs to find a way to unify patch handling extensions and tools (mainly mq, attic, shelve and record).

Attempt at capturing the situation today

Today, we have a number of overlapping extensions for managing patches on top of Mercurial repositories: mq, shelve, attic, and pbranch. It would be desirable to prune this list, optimally down to just one. However, we likely don't want to lose any of the main functionality offered by the extensions today:

mq

Goals:

Strong points:

So-so points:

Weak points:

Ideas to fix it

pbranch

Don't call it p(atch)branch call it f(eature)branch

Goals:

Strong points:

So-so points:

Weak points:

Ideas to fix it

shelve

Goals:

Strong points:

Weak points:

attic

Goals:

Strong points:

So-so points:

Weak points:

lbranch

Goals:

Strong points:

Weak points:

So-so points:

Ideas to fix it:

bundle overlay

Goals:

Strong points:

Weak points:

So-so points:

Ideas to fix it:

List of use-cases

To aid in making a good decision about the way that the functionality of these tools can be merged, several use-cases are listed here (please contribute new ones if you have one in mind that is not yet listed):

Tentative proposal

Hidden branches/heads

Add a special kind of commits heads/branches that don't get transfered during pulling/pushing/cloning. Let's call it 'hidden' branches.

They'd get transfered just when requested explicitly or when converted to normal public heads/branches.

A possible way to mark those heads/branches is using an additional extra field, similar to how closed branches are done. Removing that extra field would "unhide" the head and the branch it tips.

An alternative implementation would avoid keeping the 'hidden' property in extra and use instead some tagging for bookmarks.

In some way, this kind of branches would be similar to git topic branches, or a way to do an hg clone/pull/push -r exclusion.

Applying hidden branches to unify mq/pbranches/attic/shelve

This new kind of branches allow for a safe playground zone without resorting to full separate clones. As they can be used without propagating its changesets to other clones they're suited for history altering changes like strip, rebase, qfold or just in-progress work that's not ready to be published.

With that, the mercurial queues, pbranches or attic/shelve stores could live in the main repo instead of outside repos and this would also ease rebasing or full 3-way merging. mq, pbranch or attic would be just different ways to interface with evolving changesets.

An outline of how mq, pbranches, attic or shelve could be implemented is given:

attic

attic's shelve could move the working dir changes to a commit in a 'hidden' branch and unshelve would just merge back those changes to the working dir without (optionally) commiting them. shelves could be still named and versioned (bookmarks and/or making it a named branch would do the trick). unshelve --delete would be just a strip of the hidden branch that keeps the patch

pbranches

pbranches could be also used without the need to clone the main repo to keep tentative patches, as the pbranches could be of the hidden kind.

mercurial queues

mq could use a hidden branch to store its patches info that gets rooted at the point (changeset) where the queue is needed. When time passes and new changes are added it could be possible to rebase the mq branch to a more recent changeset and use the full rebase machinery.

Alternative approach: Overlay repositories

Instead of using hidden branches, another possibility would be using overlay repositories, with similar behaviour.

Alternative approach: Tasks

Use tasks instead of hidden branches.

Alternative approach: Plans to make attic a superset of mq

The use cases for the existing patch handling extensions could be reduced to two different feature sets / models. One that allows the handling and management of patches and its conversion into and from commits, and another one that implements a way to collaboratively develop patches.

The first feature set would merge the capabilities of mq, attic and shelve, while the second one would correspond to pbranch. Naturally, the two extensions implementing these feature sets should be highly integrated with each other.

This proposal tackles the first part, as of right now attic is already a superset of shelve and I (BillBarry) have plans to extend the functionality of attic to become a superset of mq.

General interaction with patches

Interaction with patches can be viewed from different angles:

* from how they interact with the repo history and the working copy contents: they can be working copy changes or mutable changesets.

* from how they are created: they can consolidate existing changes in the working copy or used to stash away changes those changes.

* patches can be a single set of changes or stacked, either in series, with a given order, or as unrelated changes.

Once patches are created, there's also the need to refresh its changes, apply or unapply them to the working copy or repository history, and delete them.

Conceptual user interface

Patch creation:

Patch management:

Patch transformation:

Patch removal:

Patch status:

Simplified proposed user interface for attic

(none of these commands necessarily have their final names yet)

PatchHandlingUnificationRFC (last edited 2015-06-12 08:45:03 by Pierre-YvesDavid)