Policies of repository usage

Isac is in the process of growing towards Isabelle within some years, and so does the development process organised around the Isac repository.

Cheat sheet for the commandline
Tools like TortoiseHg are useful for specific purposes (like review of local changes before a commit in order to create elegant, minimal changesets). Mercurial is handy on the command line: $ hg clone https://intra.ist.tugraz.at/hg/isac/ MYDIR $ hg st        # status $ hg fetch     # needs these records in .hg/hgrc $ hg diff      # diffs between status and last changeset $ hg ci        # commit by use of an editor $ hg push      # push local changesets to the repository, where the clone made of.

Isac adopts Isabelle's policies
The policies for using this repository follows the /README_REPOSITORY in the recent clone of an Isabelle release (which is merged into Isac's repository). Adherence to these policies in Isac development started in December 2013. This is an excerpt from /README_REPOSITORY:


 * Content discipline
 * 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.
 * Private experiments and branches should not be published by accident.
 * Study the minimal changesets at http://isabelle.in.tum.de/repos/isabelle/ in order to develop intuition, how to separate your commits into changesets of reasonable size.
 * 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.
 * Changelog entries specific to Isac development are
 * [-Test_Isac] indicating that Test_Isac does not completely succeed for very specific reasons
 * [-Build_Isac] indicating a specific show-case, which even aborts a build of session Isac.
 * Shared fetch/push access in Isac development is not that elaborated as in Isabelle. However, indispensable is to push only, if ./bin/isabelle jedit -l Isac test/Tools/isac/Test_Isac runs without any error (this takes a few minutes). The repository is world readable, both via plain web browsing and the hg client; anybody can produce a clone. For write access contact the Isabelle development team.
 * Simple merges: Before editing, fetch the latest version.

This short excerpt is an invitation to read the original /README_REPOSITORY in your Isac repository! What follows are hints how to organise personal development in order to accomplish the standards.

Hints for operating on local repositories
Indispensable seems to have at least two repositories in parallel on your computer. These repositories both must be ready to run Isabelle/Isac (this does not mean, that you have to run them in parallel: 4GB RAM is to little space for that). Let's call these repositories repo1 and repo2 and give a survey in the table how to handle them: repo1 is for experimentation and development, repo2 is for compiling changesets and meld is the preferred diff-tool:

Note that "hg fetch" in repo2 might include a merge in of updates committed by collaborators. You have to decide, whether "merge" them back to repo1 by use of the diff-tool.

As long as the Isac sources are not as stable as Isabelle's, development involves cleaning of existing sources (according to the Coding_standards_for_SML) which are worth to be preserved. If such cleaned sources do not relate to any of the "minimal changesets" compiled in repo2, then these cleaned sources should undergo a final "merge" (using meld) from repo1 to repo2, and a final "push" with the changelog entry "collected updates since changeset ...".

CHECK changesets before committing
The CHECK in the above table is bold face and uppercase for good reasons: Isac's repository serves switching back and forth between changesets for comparing respective functionalities. In order to ensure this service, the CHECK comprises the following steps:


 * (0) While editing in repo1 you have melded some updates to repo2.


 * (1) If you think you have compiled an appropriate changeset, use TortoiseHg to see, if the changeset is really "minimal" and comprehensible. Take your time and make notes for an appropriate changelog entry.

$ ./bin/isabelle jedit -l Isac test/Tools/isac/Test_Isac.thy &
 * (2) Create session Isac by


 * (3) Test_Isac must not contain any error. Important note: errors in the theories, which are imported in the header of Test_Isac, only show up in the  window.


 * (4) Before pushing you do a hg fetch. If you get in changes from other developers, you have to decide, whether these conflict with your own changes. In case of conflicts you "meld" them back to repo1 and iterate to step (0).


 * (5) After these steps were successful, use the well-considered notes for the changelog entry, commit and push to https://intra.ist.tugraz.at/hg/isa. In the rare cases, where in these seconds new commits were pushed, it is even possible to hg revert --all in repo2 for this changeset and start again from (0).

Examples for minimal changesets
As mentioned above, compiling informative and even self-explanatory changesets is an art of its own. Changeset 967c8a1eb6b1 gives a survey on a specific series of such changesets. Not all of these are optimal, so here are comments what would make them perfect.

The changelog entry of 967c8a1eb6b1 is survey on transition from "ruleset' = Unsynchronized.ref" to Theory_Data In order to keep Test_Isac running at each commit, the transition was separated into these steps: (1) restrict access to "ruleset' = Unsynchronized.ref", 9690a8d5f1c0 (2) add functions accessing Theory_Data in parallel to those accessing "ruleset' = Unsynchronized.ref", 6f1d3415dc68 (3) narrow data of Theory_Data and "ruleset' = Unsynchronized.ref", 47995aefb1c9 (4) check differences between Theory_Data and "ruleset' = Unsynchronized.ref", 0e2d1a46236d (5) iterate steps (3) and (4), 012cfda9bd83, ef98c3e15a8d, 9d1568e89775, 90546fa8b868 (6) switch from "ruleset' = Unsynchronized.ref" to Theory_Data, 967c8a1eb6b1 (7) remove all code concerned with "ruleset' = Unsynchronized.ref" and with transition; this will be done in a subsequent changeset.

The changesets addressed in the survey are:
 * (1) 9690a8d5f1c0: deletion of the outcommented code (* val (rew_ord, rls, thm, ct) = (rew_ord', id_rls rls', thm', f) ............... use"Isa99/interface_ME_ISA.sml"; *) distracts; this should have been done in a separate changeset "collected updates since changeset ...".


 * (2) 6f1d3415dc68 is fairly long, but a consequent repetition of the same kind of addition. Annoying is that the sentence in the changelog entry

Note, that the original access function "fun assoc_rls" is still outcommented; is wrong and should be Note, that the NEW access function "fun assoc_rls" is still outcommented; So, preparing the entry in a separate editor and considering the text for some minutes is highly advisable !


 * (3) 47995aefb1c9 shows how /test/Tools/isac is used for two different purposes, (a) regression tests (like the one in ADDTESTS/accumulate-val/) and (b) help for understanding and demonstration of usage (like in kestore.sml).


 * (4) 0e2d1a46236d: here it would be nice to have the two lengthy files with the output at the end; however, it is not worth the effort to tell Mercurial this special case.
 * (5) 012cfda9bd83: ok
 * ef98c3e15a8d: In case of more instructive errors a reference to the respective changeset (like in the survey) would be appropriate.
 * 9d1568e89775 shows a tiny update with great effect in Test_Isac (which can be seen by hg update 90546fa8b868).
 * 90546fa8b868: more effort than necessary is required to find out, that fun merge_rls is only minimally changed: this would be better visible, if the (important!) reformatting would have gone into a separate changeset "collected updates since changeset ...".
 * (6) e7febad0c988: This is the crucial step of the whole sequence --- without the preparatory steps one gets stuck in such comprehensive re-engineering.

Specifics
old log message old log message + file
 * (1) If you forgot to add a file then repeat the old log message and add "+ file" (without naming it -- the name is found in the diff):