Mercurial: what are the consequences of changing a phase?

Question

In Mercurial, the phase of a revision can be changed arbitrarily. What are the consequences of a phase change for all possible transitions (public, draft, secret) x (public, draft, secret)? Which phase changes are safe? Which may cause troubles and which kind of troubles? Which are more or less no-ops?

Answer 1

The default phase for a commit is draft, that's how they were treated when the phases didn't exist. When pushing a draft changeset, mercurial automatically changes its phase to public. You can use it to know which changesets you have already published or not.

But the real issue is that when the changeset is in public phase, mercurial won't let you change them with history editing extensions (like mq, rebase, etc). That's really important, because the history editing happens only in the local repository, they don't propagate with pull/push operations. So, once a changeset is published, it's out of control, it's dangerous to change it.

You can change from any phase to any other phase. The "normal flow" is to move to a higher phase (secret->draft->public), but Mercurial allows the change to a lower phase with the --force option. A phase change alone is harmless. For example, the only thing that happens when moving from public to draft or secret is that the protection of history editing is dropped, nothing else, pull and push will still work normally, Mercurial could never be confused about the changesets because they have unique identifiers. The history editing action that takes place after a phase change like this is what can cause problems. And that's why Mercurial gives the warning in the phase change and requires the --force option, as a confirmation that that's what you really want.

In general published commits shoudn't be modified, that's what the phases try to ensure. But maybe you do have control over all repositories. Or maybe you pushed something and you know that no one else pulled it yet. Whatever is the reason, you have the option of forcing the phase of the changesets back to draft and edit them. But this edition must be done in every repository that has the changesets.