Publish contributions as an external

Who should read this

This HOWTO is for people who do not have push access to the main Isabelle repository (let's call them externals) but want to contribute to Isabelle. E.g., there are feature requests, cosmetic changes, etc. (let's call them contributions) that are not essential for Isabelle to work but would be nice to have at some point. These notes provide some hints how to present and prepare contributions in order to integrate them into the main repository.

Before you start

Before even starting to work on such a contribution, you should make sure that it is reasonable and would (if worked out properly) really be integrated into the official repository. (This can easily be done by discussing the potential contribution on the isabelle-dev mailing list.)

Furthermore, there are guidelines and conventions you should adhere to during the whole process. This wiki-page is not a substitute for familiarizing yourself with those! Nevertheless, we repeat the most important points (or at least give pointers).

• Obviously you will have to work with the repository version of Isabelle (see here). This means that you should be able to use mercurial and stick to the conventions regarding user name, commit messages etc. The most important file to consult is README_REPOSITORY which is part of the main repository. Make sure to read it before you start.

• Setup your mercurial user name properly before committing any changes to your local clone of the repository. For an external, "proper" usually means

   [ui]
   username = Firstname Lastname

in either $HOME/.hgrc (for global settings) or <path to local repo clone>/.hg/hgrc (for per repository settings).

• When using the fetch extension of mercurial, avoid unwieldy commit messages for automatic merges by setting

   [defaults]
   fetch = -m "merged"

Committing changes

When committing changes to your local clone, make sure to adhere to the conventions for commit messages as given in README_REPOSITORY (note that those deliberately differ from official mercurial conventions).

In principle, it is a good idea not to postpone the publication of private commits for too long (1-3 days).

Testing changes

Before publication, pull any changes from the official repository. (This might effect a merge.) Now test your changes at least by

   isabelle build -a -o browser_info -o document=pdf -o document_graph

Moreover, if your changes might affect the AFP, they should be tested against it.

Again, do not postpone the publication of such merges for too long (0.5-2 hours).

Creating a bundle

Packaging your changes into a single file can be done with

   hg bundle somefilename.hgbundle

Publishing contributions

Finally, the previously created bundle can be send to some one with push access to the Isabelle main repository, either directly (assuming mutual agreement) or indirectly via the mailing list. An alternative is exchange through an external repository service like github.