How to contribute new code or bug fixes

Using darcs

This is the preferred option since darcs is the version control system used to manage the source code and wiki of Basilisk.

If you followed the installation instructions (using darcs), you can easily generate a new patch for the Basilisk main distribution using the following workflow:

  1. cd $BASILISK
  2. Synchronize your repo with the main branch using darcs pull.
  3. Edit the source files.
  4. Test that the changes work: add a test case, run the test suite.
  5. If you created new files, add them to the distribution using darcs add.
  6. Check that your code follows the coding style guidelines.
  7. Review and record the changes using darcs record.
  8. If you are still not happy with your patch, you can go back to 1. and use darcs amend to modify it until your are satistfied.

Note that, for consistency, the patch title should start with a capital and also be reasonably descriptive. Avoid titles such as “Modified this file”, we (through darcs) already know which files are modified by the patch, rather you should explain concisely what the patch does. Use

darcs changes | more

to see examples of patch titles and summary.

Also for consistency, your identity/authorship should be something like:

Joe Bloggs <>

You can change it by editing the $HOME/.darcs/author file.

You are then ready to submit your patch. You have two options: a simple one (email) and a more systematic one (publishing your repo).

Emailing your patch(es)

Just use darcs send -o patches (with a better name than patches) and select which patches you want to submit. Attach the patches file to an email and send it (with some explanations) to the basilisk-fr mailing list.

Publishing your repository

You can use a darcs hosting service, such as darcs hub to publish your repository. Note that both the Basilisk wiki and source code are mirrored on darcs hub. To create your own branch, login into darcs hub, go to the basilisk repo and use the fork button.

Note that if you have ssh/scp access to a web server somewhere, you can also simply copy your repository there.

To publish your changes, you can then darcs push them to this repository and send its http:// address together with your message to the mailing list.

Using Unix patches

If for some reason you don’t want/can’t use darcs, you can simply send a Unix patch to the mailing list. Let’s assume you modified src/fractions.h. You first need to get back to the original version of this file (using the original tarball, getting the raw page source on the wiki etc.) and save it as src/fractions.h.orig, then do:

diff -u fractions.h.orig fractions.h > fractions.patch

You can then review the changes in the patch file and send it to the mailing list if you are happy with it. Note that much more complex patches (for multiple files and directories etc.) can be generated. See the many online tutorials if you want to know more about patching.

Coding style guidelines

Before submitting new patches, please check that your code verifies the following conventions:

  1. It is indented properly. You should (must!) use a text editor which does this automatically. The standard indentation is two spaces. This is the default in emacs for example. In emacs you can easily indent/reindent an entire block of code by selecting it (with Ctrl-space or the mouse) and hitting the TAB key.

  2. Lines are not longer than 80 characters. If necessary reformat the code by cutting lines in logical places to make them fit. This is also true of comment/documentation blocks. Note that emacs will automatically reformat long paragraphs of text if you use ESC-q.

  3. Comments starting with “/**” are assumed to be formatted using the wiki markdown syntax. Please respect/use this. They are meant to be written using grammatically/typographically correct sentences i.e. starting with capitals, ending with ., with a subject and a verb, proper spelling etc. This is what literate programming is about.

  4. Check that your code ‘fits in’ stylistically with the existing code i.e. look around and copy what you see!. In particular, the Basilisk convention is to use “natural” punctuation/spaces. For example, commas are always followed by a space and opening and closing parenthesis are preceded (resp. followed) by a space. For readability, the ‘+’ and ’-’ operators are preceded and followed by a space, but the ‘*’ and ‘/’ operators are not.

This may seem like nitpicking but think how disagreable it is to read a text which is full of spelling mistakes and/or typographic errors. The same holds for code and, with some discipline (which is also generally useful when programming…) and some training, following the conventions above is not difficult.