improving readability of Smallcheck theory; adding constant orelse to improve performance of the function package
Important notes on Mercurial repository access for Isabelle===========================================================Introduction------------Mercurial http://www.selenic.com/mercurial belongs to the currentgeneration of source code management systems that follow the so-calledparadigm of "distributed version control". This is a terrific namefor plain revision control without the legacy of CVS or SVN. See alsohttp://hginit.com/ for an introduction to the main ideas. TheMercurial book http://hgbook.red-bean.com/ explains many more details.Mercurial offers great flexibility in organizing the flow of changes,both between individual developers and designated pull/push areas thatare shared with others. This additional power demands some additionalresponsibility to maintain a certain development process that fits toa particular project.Regular Mercurial operations are strictly monotonic, where changesettransactions are only added, but never deleted. There are specialtools to manipulate repositories via non-monotonic actions (such as"rollback" or "strip"), but recovering from gross mistakes that haveescaped into the public can be hard and embarrassing. It is mucheasier to inspect and amend changesets routinely before pushing.The effect of the critical "pull" / "push" operations can be tested ina dry run via "incoming" / "outgoing". The "fetch" extension includesuseful sanity checks beyond raw "pull" / "update" / "merge". Mostother operations are local to the user's repository clone. This givessome freedom for experimentation without affecting anybody else.Mercurial provides nice web presentation of incoming changes with adigest of log entries; this also includes RSS/Atom news feeds. Thereare add-on browsers, notably hgtk that is part of the TortoiseHgdistribution and works for generic Python/GTk platforms. Thealternative "view" utility helps to inspect the semantic content ofmerge nodes.Initial configuration---------------------The official Isabelle repository can be cloned like this: hg clone http://isabelle.in.tum.de/repos/isabelleThis will create a local directory "isabelle", unless an alternativename is specified. The full repository meta-data and history ofchanges is in isabelle/.hg; local configuration for this clone can beadded to isabelle/.hg/hgrc, but note that hgrc files are never copiedby another clone operation.There is also $HOME/.hgrc for per-user Mercurial configuration. Theinitial configuration requires at least an entry to identify yourselfas follows: [ui] username = XXXIsabelle contributors are free to choose either a short "login name"(for accounts at TU Munich) or a "full name" -- with or without mailaddress. It is important to stick to this choice once and for all.The machine default that Mercurial produces for unspecified[ui]username is not appropriate.Such configuration can be given in $HOME/.hgrc (for each homedirectory on each machine) or in .hg/hgrc (for each repository clone).Here are some further examples for hgrc. This is how to providedefault options for common commands: [defaults] log = -l 10This is how to configure some extension, which is called "graphlog"and provides the "glog" command: [extensions] hgext.graphlog =Shared pull/push access-----------------------The entry point http://isabelle.in.tum.de/repos/isabelle is worldreadable, both via plain web browsing and the hg client as describedabove. Anybody can produce a clone, change it locally, and then useregular mechanisms of Mercurial to report changes upstream, say viamail to someone with write access to that file space. It is alsoquite easy to publish changed clones again on the web, using thead-hoc command "hg serve -v", or the hgweb.cgi or hgwebdir.cgi scriptsthat are included in the Mercurial distribution, and send a "pullrequest" to someone else. There are also public hosting services forMercurial repositories.The downstream/upstream mode of operation is quite common in thedistributed version control community, and works well for occasionalchanges produced by anybody out there. Of course, upstreammaintainers need to review and moderate changes being proposed, beforepushing anything onto the official Isabelle repository at TUM. Directpushes are also reviewed routinely in a post-hoc fashion; everybodyhooked on the main repository is called to keep an eye on incomingchanges. In any case, changesets need to be understandable, at thetime of writing and many years later.Push access to the Isabelle repository requires an account at TUM,with properly configured ssh to the local machines (e.g. macbroy20,atbroy100). You also need to be a member of the "isabelle" Unixgroup.Sharing a locally modified clone then works as follows, using youruser name instead of "wenzelm": hg out ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelleIn fact, the "out" or "outgoing" command performs only a dry run: itdisplays the changesets that would get published. An actual "push",with a lasting effect on the Isabelle repository, works like this: hg push ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelleDefault paths for push and pull can be configured inisabelle/.hg/hgrc, for example: [paths] default = ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelleNow "hg pull" or "hg push" will use that shared file space, unless adifferent URL is specified explicitly.When cloning a repository, the default path is set to the initialsource URL. So we could have cloned via that ssh URL in the firstplace, to get exactly to the same point: hg clone ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelleSimple merges-------------The main idea of Mercurial is to let individual users produceindependent branches of development first, but merge with othersfrequently. The basic hg merge operation is more general thanrequired for the mode of operation with a shared pull/push area. The"fetch" extension accommodates this case nicely, automating trivialmerges and requiring manual intervention for actual conflicts only.The fetch extension can be configured via $HOME/.hgrc like this: [extensions] hgext.fetch = [defaults] fetch = -m "merged"To keep merges semantically trivial and prevent genuine mergeconflicts or lost updates, it is essential to observe to followinggeneral discipline wrt. the public Isabelle push area: * Before editing, pull or fetch the latest version. * Accumulate private commits for a maximum of 1-3 days. * Start publishing again by pull or fetch, which normally produces local merges. * Test the merged result as usual and push back in real time.Piling private changes and public merges longer than 0.5-2 hours isapt to produce some mess when pushing eventually!Content discipline------------------The following principles should be kept in mind when producingchangesets that are meant to be published at some point. * The author of changes needs to be properly identified, using [ui]username configuration as described above. While Mercurial also provides means for signed changesets, we want to keep things simple and trust that users specify their identity correctly (and uniquely). * The history of sources is an integral part of the sources themselves. This means that private experiments and branches should not be published by accident. Named branches are not allowed on the public version. Note that old SVN-style branching is replaced by regular repository clones in Mercurial. Exchanging local experiments with some other users can be done directly on peer-to-peer basis, without affecting the central pull/push area. * Log messages are an integral part of the history of sources. Other people will have to inspect them routinely, to understand why things have been done in a certain way at some point. Authors of log entries should be aware that published changes are actually read. The main point is not to announce novelties, but to describe faithfully what has been done, and provide some clues about the motivation behind it. The main recipient is someone who needs to understand the change in the distant future to isolate problems. Sometimes it is helpful to reference past changes via changeset ids in the log entry. * The standard changelog entry format of the Isabelle repository admits several (vaguely related) items to be rolled into one changeset. Each item is then described on a separate line that may become longer as screen line and is terminated by punctuation. These lines are roughly ordered by importance. This format conforms to established Isabelle tradition. In contrast, the default of Mercurial prefers a single headline followed by a long body text. The reason for that is a somewhat different development model of typical "distributed" projects, where external changes pass through a hierarchy of reviewers and maintainers, until they end up in some authoritative repository. Isabelle changesets can be more spontaneous, growing from the bottom-up. The web style of http://isabelle.in.tum.de/repos/isabelle/ accommodates the Isabelle changelog format. Note that multiple lines will sometimes display as a single paragraph in HTML, so some terminating punctuation is required. Do not squeeze multiple items on the same line in the original text!Building a repository version of Isabelle-----------------------------------------Compared to a proper distribution or development snapshot, it isrelatively hard to build from the raw repository version. Essentialcontributing components are missing and need to be reconstructed byrunning the Admin/build script by hand. Afterwards the main Isabellesystem and logic images can be compiled via the toplevel ./buildscript. Note that the repository lacks some textual versionidentifiers in the sources and scripts; this implies some changedbehavior when processing settings etc.There is no guarantee that the NEWS file is up to date at an arbitrarypoint in history.