Etiquette

The previous 3 documents describe the mechanics of installing your software publicly in the VSSP group.

This document attempts to deal with the protocol for sharing software in this way.

The VSSP group has a library of commonly used software. If the group efficiently shares software we can achieve much more than if we each perpetually reinvent the wheel. The goals of the new structure are:

To make it easy for authors to contribute and maintain their software.
To ensure that after the author leaves the group the software is sufficiently portable and documented that it can still be used and survives OS/compiler upgrades.
To ensure that the users at all levels can easily find out about and use the libraries and executables.
To adhere to a small set of software engineering standards as far as is possible.
To achieve easy multi-architecture operation, that can survive as far as possible the removal of one disk/node in the network.

It is expected that most members of the group will place some of of their more useful software in the public domain towards the end of their project. If in doubt, your supervisor will advise on what should be publicly installed.

However it will help to bear the package guidelines in mind throughout development, to avoid a major rewrite at the end.

This system will only work if users are prepared to be tolerant and cooperative. Some do's and dont':

The author has [probably] put a lot of work into their product:
- Dont treat a bug as a personal insult, even if you lost half a day trying to locate the problem, it would still take you much longer to write your own program.
- Dont copy their program, delete their header, and try and pass it of as your own.
Cite other peoples work properly. i.e. if their algorithm was published, cite the paper, or if their code helped you produce a result, acknowledge it in your paper/thesis.
It is almost always unnecessary to keep private copies of public packages in your own home directory. If you have a good reason to make your own copy ask the author first. If you do have an out of date private copy dont expect support from the author.
Always consider how to write your private software so that it can be of use to others if you expect it will be included in public domain later
Document, document and document. your code should be commented, man pages, doc files, READMEs.
Dont make changes to public copies without doing at least a few basic tests. It can take users hours to figure out whats suddenly going wrong.

A.Stoddart@ee.surrey.ac.uk

August 1994