Guidelines for different content types: Headers
Most file types are requested to contain a header section if uploaded to the openVT platform. While it is up to you to decide how technically you include the header in your file, the header must always be clearly identified as such. That can be as a commented section at the beginning of the file, as a docstring (if that is supported in the respective file type), as a section marked with begin header/end header, etc.
There is a number of information which minimally should be included in the header:
- title, version number and very short description of the content of the file,
- author(s) of the file, eventually including affiliation(s) and contact information(even though user-developer interaction should preferably be done via the issue tracking board, this might still be handy beyond the official end of the VIRTUAL project),
- link to VIRTUAL and to license agreement,
- dependencies, i.e. files or packages (including version numbers) either on the openVT platform or external that this file depends on,
- anything else you feel like a later user ABSOLUTELY needs to know.
- It is possible (and recommended) to link to external resources, e.g. scientific publications, to explain methods used, parameters set etc. In this case, use DOI to permanently link to these resources.
- The revision history should not be part of the header. Instead, it should be documented in the version control system of the openVT platform. Use the comment function of the version control system to wisely comment any commit!