Status 12.11.2018: DRAFT
Publishing software is different from getting it to work on the programmer’s machine or on the machines of a small research group. This guideline is intended as a short guide to define the minimal steps necessary to prepare a software publication at the Language Bank of Finland.
The software needs
If an older version of the same software exists, a decision needs to be made whether to update metadata in an existing description or to create new metadata. An update is recommended if the new version fixes bugs (a ”patch”), a separate metadata page is recommended if the new version offers new or concurrent functionality, i.e. if there is reason to keep the old version online.
The package has to have a license to inform the user what he or she can and cannot do with the software. Less restrictive licenses are preferred, the license should be stated in the README.txt or a LICENSE.txt file.
Software without a manual and a description cannot be published. Both can be short, but they have to be present. The manual describes how to install and use the software. The manual can be a set of files in the package, like README.txt, INSTALL.txt, MANUAL.txt depending on the complexity of the software.
It should contain:
The descriptive metadata describes a specific instance of the software. It is not a manual, but helps a user searching for software to determine whether the software is worth downloading. The PID pointing to the metadata is the persistent identifiert of the software version in question. The metadata in turn points to the download location of the software and explains where the manual can be found (e.g. inside the package or on a separate web page). Every update gets a new version number. We follow ”Sematic Versioning”: Major.Minor.Patch. New patches can be updated without changing the PID of the metadata, Major and Minor update usually require a new metashare page and the retirement of the now obsolete version. The metadata should also contain the license information. The PID of the metadata needs to be mentioned in the README.txt of the downloadable file.
To update the major or minor version a new metashare page needs to be created describing the new version and a change log relative to the present version. 2 new PIDs need to be created, one pointing to the metadata and one to the new download location. The related versions need to be linked using Metashare’s relations feature, see the Language Bank’s Language Resource Life Cycle Model An example from our corpora: http://urn.fi/urn:nbn:fi:lb-2016050401. The older version should be kept for at 5 years, either online for download or offline in IDA. Software older than 10 years can be deleted, unless it has historical value.
If the new version has no new functionality and is only a patch (eg. 1.1.1), no PIDs need to be updated, the publication of the new version needs to be marked in the Change Log of the metadata. The non-patched version should be kept in IDA for 5 years just in case.
Consider finnish-tagtools version 1.1: http://urn.fi/urn:nbn:fi:lb-2018062101. The metadata describes the software, the license and where more information about using the software and technical support can be found. A rough update shedule is also given. The update to Version 1.2 should happen as described in ”Significant updates” above: A new metashare page needs to be written, with a Change Log section in the description descibing the main new features/bug fixes. If the old version should not be kept online, the access location PID needs to be changed to a tombstone page describing that the software can be obtained from IDA.
A quick reminder of the topics above.