Call for discussion: Phase names

[Olav Reinert]

Hi all,

At the 2.1 mini-spring in Zürich last week-end, the names of the phases were discussed quite a lot, and it has also been a topic of much discussion here on the mailing list.

In order to reach a useful consensus in time for the 2.1 code freeze in mid-January, Pierre-Yves DAVID from Logilab has asked me to organize a conclusive discussion to decide on the phase names to use in the final release.


The current (unacceptable) naming scheme is as follows:

    Name    Immutable   Shared
    public      X         X
    draft                 X
    secret

(Even though the names of the changeset properties assigned to the phases (immutable and shared) have also been debated, their meaning is not disputed.

Most people seem to agree that "draft" is a good name for the middle phase, because it implies a work-in-progress that may be shared. The name "public" is disliked by some because it doesn't convey immutability, which is an important and distinguishing property of that phase. The name "secret" is disliked because to some it suggests enforcement of confidentiality (i.e., that it's safe to check in trade secrets or nuclear launch codes), which is not the case, and not intended, either.


The phase names ought to conform to the rules described here:

    <http://mercurial.selenic.com/wiki/StatesPlan#Naming>

To summarize: The three phase names must have unique initial letters, and should preferably be short. Because we intend to use those initial letters as single-letter option names, they should not clash with other common options, such as -f (for --force); hence, phase names like "final" will face resistance. Finally, it is a plus if the name works in common UI sentences such as "Nothing to push but 42 secret changesets".


Previously suggested naming schemes are:

    complete / draft / private
    public / draft / grounded
    public / draft / jailed


Alternative names suggested for the "public" phase:

    complete, absolute

Alternative names suggested for the "secret" phase:

    personal, mine, isolated, tentative, shy, scratch, jailed, moored, anchored, grounded


To kick off the discussion, my preferred naming scheme is the following:

                Mutable Grounded
    published
    draft           X
    grounded        X       X

and I think the changeset properties should be changed to (mutable, grounded).

I like the name "draft", and I like that the other two names are verbs in the past tense, because you arrive in such a phase due to some action. Also, "published" connotes something that's shared and immutable, whereas "grounded" means something that can change, but may not take off somewhere (think teenagers or airplanes).

Note that I have also shown how the binary changeset properties are assigned to phase names, and how monotonicity is preserved (i.e., consistent addition or removal of properties when moving through phases in one direction). If you wish to propose new names for the phase properties, you must provide a similar table, and your suggestion must also be monotonic.


So, there it is - please get creative and submit your proposals. Hopefully, some consensus will form via the mailing list discussions. If not, perhaps we need to organize a vote. We will decide that towards the end of the week.

Thanks,

Olav (and Pierre-Yves)