docs/versioning.rst

   1 Versioning
   2 ==========
   3
   4 Documentation about OpenDaylight's upstream versioning.
   5
   6 Overview
   7 --------
   8
   9 Opendaylight has a variety of types of version numbers. Internal ODL features
  10 have versions, but they are not visible to external consumers of OpenDaylight.
  11 OpenDaylight, built into a distribution of many features, has a version number.
  12 OpenDaylight is repackaged in a variety of formats (RPMs, .debs, Docker images,
  13 Vagrant base boxes, etc) and follows the guidelines for each. OpenDaylight
  14 packages are consumed by configuration management tooling (Ansible, Puppet),
  15 which also have their own types of versioning.
  16
  17 RPMs
  18 ----
  19
  20 The RPM versioning follows the `Fedora Packaging Guidelines`_.
  21
  22 - Major Version numbers that increment with each Simultaneous Release (5=Boron,
  23   6=Carbon, 7=Nitrogen, 8=Oxygen...).
  24 - Minor Version numbers that increment with each Service Release (5.0=Boron,
  25   5.1=Boron SR1, 5.2=Boron SR2...).
  26 - Patch Version is currently unused.
  27 - Package Version numbers that increment for each new package build of the same
  28   ODL build (5.0.0-1=Boron, 5.0.0-2=Boron with RPM update).
  29 - Snapshot/autorelease versions with timestamps and incrementing build numbers
  30   for pre-release builds (8.0.0-0.1.20171020rel2011=Oxygen pre-release
  31   autorelease build, 8.0.0-0.1.20171101snap835=Oxygen pre-release snapshot
  32   build...).
  33
  34 See the OpenDaylight builds on the `Nexus`_ or the `CentOS`_ Community Build
  35 System for examples.
  36
  37 Debs
  38 ----
  39
  40 Mostly the same as RPMs, slightly different way of denoting pre-release builds.
  41
  42 Docker Images
  43 -------------
  44
  45 Docker uses Major, Minor and Patch versions. It doesn't support pre-release
  46 version numbers, which is okay since we don't currently build Docker images for
  47 pre-release versions. See the `tags of the opendaylight/odl image`_ for
  48 examples.
  49
  50 Vagrant Base Boxes
  51 ------------------
  52
  53 Vagrant follows `Rubygems versioning`_, which uses Major, Minor and Patch
  54 versions for semver. It doesn't support pre-release version numbers, which is
  55 okay since we don't currently build Vagrant base boxes for pre-release
  56 versions. See the `versions of the opendaylight/odl base box`_ for examples.
  57
  58 Ansible Role
  59 ------------
  60
  61 The Ansible role follows `Semantic Versioning`_. Version bumps are based on API
  62 changes. Backwards incompatible API changes cause Major Version bumps,
  63 backwards compatible API changes cause minor version bumps, bugfixes and minor
  64 updates can be batched into patch version bumps.
  65
  66 Puppet Module
  67 -------------
  68
  69 The Puppet module follows `Semantic Versioning`_. Version bumps are based on
  70 API changes. Backwards incompatible API changes cause Major Version bumps,
  71 backwards compatible API changes cause minor version bumps, bugfixes and minor
  72 updates can be batched into patch version bumps. See the `changelog`_ and
  73 `metadata`_ for examples of correctly bumping versions.
  74
  75 .. _Fedora Packaging Guidelines: http://fedoraproject.org/wiki/Packaging:Versioning
  76 .. _Nexus: https://nexus.opendaylight.org/content/repositories/opendaylight-oxygen-epel-7-x86_64-devel/org/opendaylight/integration-packaging/opendaylight/
  77 .. _CentOS: http://cbs.centos.org/koji/packageinfo?packageID=755
  78 .. _tags of the opendaylight/odl image: https://hub.docker.com/r/opendaylight/odl/tags/
  79 .. _Rubygems versioning: http://guides.rubygems.org/patterns/#semantic-versioning
  80 .. _versions of the opendaylight/odl base box: https://app.vagrantup.com/opendaylight/boxes/odl
  81 .. _Semantic Versioning: http://semver.org/
  82 .. _changelog: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CHANGELOG
  83 .. _metadata: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=metadata.json;h=713b3ef3f602ac5fdc4d11b655b8acf9f6908639;hb=HEAD#l3