States Plan

This page is intended for developers For more generic details check MutableHG page

1. Changeset phases

A 'changeset phases' is an indicator that tells us how a changeset is manipulated and communicated. The details of each phase is described below, here we describe their shared properties.

Like bookmarks, phases are not stored in history and thus are not permanent and leave no audit trail.

First, no changeset can be in two phases at once. States are also ordered, so they can be considered from lowest to highest. The default, lowest phase is 'publich' - this is the normal phase of existing changesets. No child changeset can be in a lower phase than its parents.

The proposed phases are:

public < draft < secret

These phases share a hierarchy of traits:

These names are subject to change. See the Naming section.

1.1. Usage

The current phase of changesets is displayed in the log with a 'phase:' header. The public phase is not displayed at all.

There are corresponding revset predicates for each phase as well.

Most phase change are will be made automatically by standard mercurial command. Read each phase section for details.

States are manipulated via the 'hg phase' command, ie 'hg phase -p x' to mark x as public. Each phase puts its own constraints on how it can be manipulated.

1.2. Implementation

Contexts provide a phase() method that returns the current phase as an integer. Contexts provide a phasestr() method that returns the current phase as a string.

public phase is stored as 0, draft phase is stored 1, secret phase is stored 2

2. Public changesets

Public changesets are changesets that are considered permanently immutable. This matches the history model presented by legacy Mercurial: changesets cannot be changed or removed without using history editing features from extensions. The name reflect the fact that once a changeset is published, it becomes very difficult to remove it from distributed history.

2.1. Usage

Changeset are automatically set in the public phase when they are know to exist outside the repository. This behaviour can be altered using the publish option describe in the draft changeset section.

• changeset pulled are public
• changeset pushed are public
• changeset unbundled are public

Changeset can be manually moved to the frozen phase via 'hg phase --frozen X'.

Tagged changeset should probably be public

2.2. implementation

2.3. Legacy clients

N/A

3. draft changesets

draft changesets are changesets that the user is permitted to use history-modifying operations like rebase or mq on. They may not be tagged. They may also be thought of as 'unpublished'.

Various operations such as pushing to other repo will move changesets into the public phase. Changesets cannot be moved from public to draft without a forcing operation.

A phase.publish option will allow exchange of changeset without moving them in the public phase.

• Changeset adding changeset to a phase.publish=True server are set public.
  • This is the default.
• Changeset adding changeset to a phase.publish=False server do not alter they
  • phase. This allows people to collaborate on work in progress before it becomes finalized.

The phase of changesets are communicated between compatible servers and clients.

This should generally be engineered such that users don't have to give any additional thought to draft vs public in their day-to-day usage.

3.1. Usage

Changesets must be in a draft phase when they are created. So new commits will start in a draft phase by default.

3.2. Implementation

The set of draft changesets is stored as a list of draft roots. All descendants of these roots are draft (or in a higher phase). This set is known as the 'draft barrier' and defines the 'draft set'. This barrier is intended only to advance.

The draft barrier is communicated via the pushkey protocol to servers that support it. The client is responsible for advancing the barrier on both the client and server sides. On each operation, the client reduces the phase set on both sides to the intersection of the sets on the client and server. That is, if a changeset is frozen on either side, it becomes frozen on both sides.

By default servers are configured as 'publishing servers'. Legacy servers are publishing servers by default. These are recognized by not having the 'phase' pushkey namespace. When pushing to a publishing server, all pushed changesets are moved into the public phase on the client. Similarly, all changesets pulled from a publishing server are treated as public

3.3. Legacy clients

See above for pushing to legacy clients. Legacy clients are allowed to pull draft changesets, though a round trip will make them public.

4. secret changesets

secret changesets are changesets that are not visible to remote clients. This is useful to mark work private and to avoid inadvertently publishing changesets.

4.1. Usage

secret changesets (and their descendents) can be marked with 'hg phase --secret'.

4.2. Implementation

Like draft changesets, secret changesets are implemented via a local barrier set. This set is used to filter changesets from remote clients for push/pull/hgweb.

4.3. Legacy clients

Legacy clients cannot see secret changesets so will not pull them. New clients will not push secret changesets by default

5. Naming

Until these names are officially nailed down, please use the names above for discussion of the concepts.

The 'state' name is somewhat problematic because it's rather overloaded already and conflicts with hg stat. Thus 'phase' is maybe a better choice.

The 'frozen/liquid/local/dead' name set is also not ideal. The ideal set of state names will:

• all be on an obvious continuum or theme
• not have conflicting initials (liquid vs local)
• not conflict with common options (frozen vs force)
• not insist too much on a particular workflow (review)
• imply that changesets states can be moved only in one direction (frozen vs public)
• shouldn't conflict with the attributes of states (mutable, hidden)
• have fairly obvious semantics

Current proposals:

• public < draft < secret < ?

Discarded proposals:

• public < local < secret < ? (local is a bit misleading, doesn't imply mutability)

• public < local < private (initials clash)

• published < review or ready < draft < trash (review or ready is a bit too much workflow)

• published < mutable < private < discarded (mutable isn't thematic, conflicts with attributes)

From a UI perspective, transitions between states are done either implicitly or by setting a state. So there should be no 'freeze' or 'publish' verb in the UI.

6. Controlling and Hooking on phase movement

6.1. Basic use case for control

I expect this use case to be a good mirror of how we would like to use phase at Logilab or for mercurial development. There is three kind of people working with three kind of repo.

6.1.1. People

This scenario includes three kind of people :

:Developer: are part of a team that write code and create changesets. They are not allowed to validate their own changesets.

:Admin: are part of the same team but are allowed to validate changeset.

:External: are not part of the team and not allowed to validate their changesets either.

Note: In this team, only a few people are allowed to validate changesets, but it could be different, for example with everyone but the interns allowed to validate their changesets.

6.1.2. Repositories

This scenario includes three kind of repositories:

:Public: is the repository used as a reference for the project. The phases.publish option is set to True. Only people:admin people are allowed to push to it. For the mercurial project it is the repository available at http://selenic.com/hg

:Devel: is a development repository used by the team. The phases.publish option is set to False. Both people:developer and people:admin can push to it but only people:admin are expected to move the phase boundary to mark changeset as validated and immutable.

:External: repositories created and controlled by people:external where they work on their contributions. The core development team can only pull contribution from these repositories.

6.1.3. Vocabulary

• people:XXX refer to a mercurial user in the group XXX described above.
• repo:XXX refer to a mercurial repositoty in the group XXX described above.
• phase:Public refer to the 0 phase in which a changeset are immutable
• ctx:X refer to a changeset "X"

6.1.4. Expectation

We need a way to make sure no changeset can be set in the phase:Public by something else than being pushed into repo:Public.

Below are some variants:

• We don't expect changeset of repo:Devel to in the public phase if they are not in repo:Public.
• Phase movement on repo:Devel should be only accepted is triggered by
  • pull from repo:Public
  • push from people:admin
• Changeset in a repo owned by people:devel of people:external should not be
  • set in public phase by something else than pulling from repo:Public or repo:Devel

6.1.5. Examples

6.1.5.1. Example A

• (1) A people:Admin push ctx:A to repo:Public (2) A people:Developer pull ctx:A from repo:Public. The phase:Public boundary
  • move to ctx:A
  (3) The same people:Developer push ctx:A to repo:Devel. The public:Phase boundary move
  • to ctx:A
• A.1 MUST be allowed
• A.2 MUST be allowed
• A.3 COULD be allowed

6.1.5.2. Example B

• (1) A people:Developer make ctx:B public locally. (2) The same people:Developer push ctx:B to Dev. Public phase boundary move
  • to B
• B.1 COULD be denied. But we can't ensure it is.
• B.2 MUST be denied

6.1.5.3. Example C

• (1) A people:Developer set ctx:C as phase:Public locally (2) A people:Admin pull from people:Developer which have publish=False.
  • phase:Public boundary move to ctx:C
  (2) The same people:Admin push to repo:Devel. The phase:Public
  • boundary move to ctx:C
• C.1 COULD be denied. But we can't ensure it is
• C.2 and C.3 are more about people:Admin making a mistake. But if the phase
  • movement is silent enough it won't be hard to make such mistake.

6.1.5.4. example D

• (1) A people:Developer set ctx:D as phase:Public locally (2) Another people:Developer pull from the first one. The phase:Public
  • boundary move to ctx:D
  (3) The second people:Developer push to Dev. The phase:Public boundary
  • move to ctx:D
• D.1 COULD be denied. But we can't ensure it is.

• D.2 CAN NOT be denied if we what to stay a Decentralized VCS (make it

  • clear by having a case where dev exchange valid public changeset)
• D.3 SHOULD be denied (this conflict with A.1)

6.1.5.5. example E

• (1) A people:External push ctx:E to it's repo:External repo using old
  • mercurial version.
  (2) A people:Developer pull ctx:E from repo:External. The phase:Public
  • boundary move to ctx:E
  (3) The same people:Developer push ctx:E to repo:Devel for sharing. The
  • phase:Public boundary move to ctx:E.
• E.1 Is not something we have control on.
• E.2 SHOULD not deny the pull but COULD deny the phase movement (at least warn about it)
• E.3 MUST be denied

6.2. Basic use case for hook

MQ: When mq managed changeset move from secret to ready (or public) mq will want to detect it and either:

• qfinish those patches
• Abort the transaction

QA: When changeset are made public QA bot may trigger.

SYNC: When changeset are made public in a devel repo, automatic sync with public repo may be wished.

6.3. Hook change

The way to controll this should be through hooks. Bellow is proposal

6.3.1. existing hook change

The following existing hooks familly might receive and additional argument about phase:

• changegroup
• commit
• incoming
• outgoing

They would receive a new argument $IN_PHASE. This argument hold a generic information about the maximum phase the changeset may take.

This would affect the following case:

• hg unbundle into publish == True

  • changegroup IN_PHASE=0

  • incoming IN_PHASE=0

• hg unbundle into publish == False

  • changegroup IN_PHASE=1

  • incoming IN_PHASE=1 (I'm not sur bundle should be seens as public or not…)

• hg pull into publish == True from publish == True

  • changegroup IN_PHASE=0

  • incoming IN_PHASE=0

  • remote outgoing IN_PHASE=0

• hg pull into publish == True from publish == False

  • changegroup IN_PHASE=0

  • incoming IN_PHASE=1

  • remote outgoing IN_PHASE=1

• hg pull into publish == False from publish == True

  • changegroup IN_PHASE=1

  • incoming IN_PHASE=0

  • remote outgoing IN_PHASE=0

• hg pull into publish == False from publish == False

  • changegroup IN_PHASE=1

  • incoming IN_PHASE=1

  • remote outgoing IN_PHASE=1

• hg push from publish == True to publish == True

  • remote changegroup IN_PHASE=0

  • outgoing IN_PHASE=0

  • remote incoming IN_PHASE=0 (how should it know about it ?)

• hg push from publish == True to publish == False

  • remote changegroup IN_PHASE=1

  • outgoing IN_PHASE=0

  • remote incoming IN_PHASE=0 (how should it know about it ?)

• hg push from publish == False to publish == True

  • remote changegroup IN_PHASE=0

  • outgoing IN_PHASE=0

  • remote incoming IN_PHASE=1 (how should it know about it ?)

• hg push from publish == False to publish == False

  • remote changegroup IN_PHASE=1

  • outgoing IN_PHASE=1

  • remote incoming IN_PHASE=1 (how should it know about it ?)

• hg commit

  • commit IN_PHASE=1

• hg commit --phase=secret

  • commit IN_PHASE=2

• hg commit --phase=public

  • commit IN_PHASE=0

6.3.2. Introducing new hook

I can see two new possible famillies of hook:

movephase: triggered when we move phase boundary locally.

• reason (commit, pull, push, remotepush, addchangegroup, unbundle, other (eg manual))
• source
• publishing_source (true or false)
• user ?
• boundaries (how to serialise this for shell…)

pushphase: triggered when we send phase data to remote

• source (aka remote)
• user ?
• publishing_source (true or false)
• boundaries (how to serialise this for shell…)

Stuff that move phase:

• hg commit
• hg pull
• hg push
• hg unbundle

The more details we can get about phase movement is

• hg commit:
  • premovephase with precommit
  • prexnmovephase with prexncommit
  • movephase with commit
• hg pull
  • (Do we need something before discovery ?)

  • premovephase

    • before we pull changegroup (move computed using remote phase data) ? (phase did not moved yet)

  • prexnmovephase after we pull changegroup (move computed using remote phase data).

    • (phase did moved)

  • movephase after changegroup have been added (or nothing to pull)

    • (phase did moved)
• hg push
  • (Do we need something before discovery ?)

  • premovephase before we push changegroup (move computed using remote phase data ?)

  • prepushphase before we push changegroup (move computed using remote phase data ?)

  • prexnmovephase after we pushed changegroup but before we push phases to remote

  • prexnpushphase after we pushed changegroup but before push phases to remote

  • pushphase after changegroup have been pushed (or nothing to push) and phase pushed

  • movephase after changegroup have been added (or nothing to pull) and phase pushed

=== Solving usecase with Hook===

6.3.3. Control usecase

repo:Devel set a premovephase hook that deny phase move for user outside people:Admin. This deny A.1, B.2, D.3, E.3

people:Admin set a movephase hook that display warning when movephase is called on something else than:

• local operation

• pull from repo:Public

• push to repo:Public

people:Developer set a movephase hook that display flashy warning when movephase is called on something else than:

• pull from repo:Public

people:Developer set a pushphase hook that display flashy warning in all case:

Edit conflict - other version:

Edit conflict - your version:

End of edit conflict

6.4. other case

MQ: can use a prexnmovephase hook to deny pull over mq patches.

MQ: can use a movephase hook to qfinish mqpatch made public.

QA: can use movephase hook to trigger build bot.

SYNC: can use movephase hook to trigger build bot.

7. Implementation status

8. Done

• Basic phase mechanism. phase summary can be move and are properly

  • save in mercurial transaction.

• Public and draft phases. Changeset are committed as draft. Changeset are

  • set as public on exchange operation.

• Public changeset are immutable, rebase and mq refuse to delete them.

9. Implementation in progress

• phase.publish option to control if echanged changeset are set in the public
  • phase.
• Exchange phase boundary exchange
• secret phase

10. Still in discussion

• Hooks on Phase movement

CategoryDeveloper