Software Development Guidelines

Overview

One of the main goals of the Open Planets Foundation is to SUPPORT the development of maintainable "turn-key" digital preservation software.

To this extent we recommend that a simplistic well utilised strategy be employed when developing software, keeping use of many disparate services to a minimum where possible. 

The Open Planets Foundation recommends using GitHub to manage source code control and to provide the following features:

• To put the software description and README
• To manage your source code
• To manage branches and tags
• To manage releases and packaging code
• To keep track of issues relating to the code
• To manage a roadmap via the issue tracker

Further to this the Open Planets Foundation main website has a series of software pages that are automatically populated from content in github, so you are in control of your piece of software. 

Getting your software listed and supported by OPF

For the most part this process is reasonable strait forward however there are a number of criteria that MUST be met prior to formal listing on the OPF website being offered. 

Of course, support will be provided where possible in improving your software development process to meet these criteria.

Note: Getting listed on the website does not guarantee support, but meeting the criteria outlined here will certainly help both you and the future of any software. 

The Software Development Criteria

In brief these criteria are:

Version Control System Usage and Package Files:

• Your software MUST be developed in an version control system.
• The software MUST have a good name (descriptive and not project based).
• The software MUST have a good description that enables people to search for what it does, not it's complicated name. 
• Any releases of the software MUST have a directly related tag in your version control system.
• It is RECOMMENDED you use a GNU-Standard 3 digit version numbering system X.Y.Z
  • X = API Change that could break interoperability
  • Y = API, Style or Feature change that does not break interoperability
  • Z = To be used for bug-fix releases only
• You MUST use an issue tracking system to log bugs and feature requests. 
• You MUST keep an accurate changelog (via detailed commit messages is best)
• You MUST provide INSTALL text files detailing both binary and from source installation methods.
• You MUST provide a HOWTO guide on using your tool, via README, User Manual or even better a linux manpage.
• You SHOULD where possible provide examples (including test files if applicable) such that a user can witness the tool working.

Installation Requirements: 

• You *SHOULD, *where possible, provide binary versions and installers for your software, e.g. a windows binary, debian and redhat package.
• The software MUST be installable with the latest stable and supported versions of applications as dictated by the latest supported operating system: 
  • Linux (for debian) installs MUST work on the latest LTS release of Ubuntu and MUST NOT require newer versions of packages not supported by the OS. 
  • Linux (for redhat) installs MUST work on the latest Enterprise release of Redhat and MUST NOT require newer versions of packages not supported by the OS. 
  • Windows installs MUST work on Windows 7 and again not require any unstable or beta versions of any supporting software. 
  • OS X installs MUST work with the latest operating system, this may involve development of "walled in" software.

• Software not supported in these environments is unlikely to be installed by users.

Binary Packages:

• Binary packages MUST meet all the requirements as set out by the community standards (e.g. for debian be lintian clean)
• Binary packages SHOULD be signed with a registered developer key to ensure authenticity (note that OPF can do this for you with their key)

Making the OPF Software Page Work For You

1. Name and Description
   1. The name comes from the GitHub project name (less the prefix)
   2. The description comes from the description on your GitHub project page. 
2. Downloads and Packages
   1. Debian/Ubuntu downloads come from the deb.openplanetsfoundtion.org repository automatically (so whatever version is signed and in that repository is the one which is linked to)
   2. Redhat/Fedora downloads come from the rpm.openplanetsfoundtion.org repository automatically (see above)
   3. Windows installer files are sourced from your github downloads page, they need to be named package-name_X.Y.Z_win32 or package-name_X.Y.Z_win64
3. Resources 
   1. User Manual links are sourced from your github downloads page, the file needs to have the string "UserManual" in it somewhere.