Best Practice Software Release

Find more best practices here: BestPractice.

Software Naming Conventions

General rules

• Entire release name are written in lower case letters.
• We try to follow the guidelines described in Semantic Versioning: http://semver.org/:
  "Given a version number [{major}.{minor}.{bugfix}], increment the:
  1. [{major}] version when you make incompatible API changes,
  2. [{minor}] version when you add functionality in a backwards-compatible manner, and
  3. [{minor}] version when you make backwards-compatible bug fixes. Additional [-{qualifier}-{number}] for pre-release and build metadata are available as extensions to the [{major}.{minor}.{bugfix}] format."

The following scheme is for naming 52N software release binaries:

52n-{project}-{major}.{minor}.{bugfix}[-{qualifier}.{number}].{filename suffix}

The -{qualifier}.{number} is optional (therefore in square brackets).

Here are some samples of possible releases binary names:

• 52n-wps-9.0.0-alpha.1.zip
• 52n-wps-9.0.0-beta.1.zip
• 52n-helgoland-4.0.0-rc.3.zip
• 52n-sos-5.2.4.zip

Valid Qualifiers

We consider the following qualifiers and their semantics as valid (descriptions taken from Wikipedia):

• alpha:
  "[...] software can be unstable and could cause crashes or data loss. Alpha software may not contain all of the features that are planned for the final version. [...] The alpha phase usually ends with a feature freeze, indicating that no more features will be added to the software. At this time, the software is said to be feature complete."
• beta:
  "[..] software is feature complete but likely to contain a number of known or unknown bugs. Software in the beta phase will generally have many more bugs in it than completed software, as well as speed/performance issues and may still cause crashes or data loss."
• rc (release candidate):
  "[...] all product features have been designed, coded and tested through one or more beta cycles with no known showstopper-class bugs." During this phase, no additional feature are implemented, only bugs are fixed.

Plugin/Extensions Specifics

Some software projects are plugins or extensions for existing (52n or other) software (e.g. ILWIS plugins). Code compatibility of a plugin MUST be given on a major release. Thus the following naming convention applies for plugins:

52n-{project}-{major}.{minor}-{plugin-major}.{plugin-minor}.{plugin-bugfix}[-{plugin-qualifier}.{qualifier-number}].{filename suffix}

Here: {major}.{minor} denotes the minimum api version that is required.

Here are some examples of possible extension names:

• 52n-sos-4.0-sos-extension-2.0.0.jar (sos-extension in version 2.0.0 compatible with 52N SOS starting from version 4.0)
• 52n-ilwis-3.5-ilwis-python-1.2.3-rc.1.zip (ilwis-python plugin in version 1.2.3-rc.1 compatible with 52N ilwis starting from version 3.5)

Git Pre-/Release Tag Naming

As we are using git and GitHub for distributing our software (see 52north.github.io), the release tags MUST follow the previously mentioned conventions. This results in the following schema:

v{major}.{minor}.{bugfix}[-{qualifier}.{number}]

Here are some samples in analogy to the previously used examples:

• v9.0.0-alpha.1
• v9.0.0-beta.1
• v4.0.0-rc.3
• v5.2.4
• v5.x-2.0.0 (plugin / extension)
• v3.x-1.2.3-rc.1 (plugin / extension)

This is how it MUST NOT be:

This is how it SHOULD be:

Bad Example

You MUST NOT do following

1. superwis things 2.0 beta 1.0
2. superwis things 2.0 beta 1.1
3. superwis things 2.0 beta 2.2
4. superwis things 2.0 beta 3.0

but this is ok

1. superwis-things-2.0.0-beta.1
2. superwis-things-2.0.0-beta.2
3. superwis-things-2.0.0-beta.3
4. superwis-things-2.0.0-beta.4

Software Release Workflow

1. Developer: Create release tag following the conventions above in your github master branch and push it to github:

   git tag v4.0.0-rc.3 && git push --tags

2. Developer: Create release draft: https://github.com/52North/<project>/releases/new
   1. Refer to the previously created and pushed branch tag from master branch.
   2. Enter a speaking title using this convention: {project} {major}.{minor}.{bugfix}[-{qualifier}-{number}], e.g. "Helgoland 4.0.0-rc.3"
   3. Give a short description of the release including or link to the change logs, release notes, and version.
   4. Create binary distributable of the release. Don't forget to include README.[txt|md] or a RELEASE-NOTEST.[txt|md], LICENSE.[txt|md], potentially database set-up files, and some offline documentation files (see BestPracticeReleaseReadme).
      Attach each binary to the release using the github form (consider size limit of 2GB per file).
   5. Select This is a pre-release if this is not a final relase but an alpha, beta, or rc version.
   6. Save the draft.
3. Developer: Send link to release draft to Ann (a.hitchcock@52north.org) stating when the release can be published.
4. Ann: Archive release binaries in company internal archive for releases.

Which files belong where

• Release files binaries belong to the github release as attachments. Consider the file size limit of 2GB per file ofgithub.
• Configuration files should be included in the the binary release zip files.
• Larger files and user manuals should be hosted in the community file folders: http://52north.org/files/<community name>

Additional/other files

Additional files like tutorials and example data should be stored in the communities' files webdav located at https://52north.org/files/ <community name> , e.g. http://52north.org/files/sensorweb/osgeo-live/ for osgeo-live related files of the Sensor Web community.