doc/guides/contributing/stable.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2018 The DPDK contributors
   3
   4 .. _stable_lts_releases:
   5
   6 DPDK Stable Releases and Long Term Support
   7 ==========================================
   8
   9 This section sets out the guidelines for the DPDK Stable Releases and the DPDK
  10 Long Term Support releases (LTS).
  11
  12
  13 Introduction
  14 ------------
  15
  16 The purpose of the DPDK Stable Releases is to maintain releases of DPDK with
  17 backported fixes over an extended period of time. This provides downstream
  18 consumers of DPDK with a stable target on which to base applications or
  19 packages.
  20
  21 The primary characteristics of stable releases is that they attempt to
  22 fix issues and not introduce any new regressions while keeping backwards
  23 compatibility with the initial release of the stable version.
  24
  25 The Long Term Support release (LTS) is a designation applied to a Stable
  26 Release to indicate longer term support.
  27
  28
  29 Stable Releases
  30 ---------------
  31
  32 Any release of DPDK can be designated as a Stable Release if a
  33 maintainer volunteers to maintain it and there is a commitment from major
  34 contributors to validate it before releases.
  35 If a version is to be a "Stable Release", it should be designated as such
  36 within one month of that version being initially released.
  37
  38 A Stable Release is used to backport fixes from an ``N`` release back to an
  39 ``N-1`` release, for example, from 16.11 to 16.07.
  40
  41 The duration of a stable is one complete release cycle (4 months). It can be
  42 longer, up to 1 year, if a maintainer continues to support the stable branch,
  43 or if users supply backported fixes, however the explicit commitment should be
  44 for one release cycle.
  45
  46 The release cadence is determined by the maintainer based on the number of
  47 bugfixes and the criticality of the bugs. Releases should be coordinated with
  48 the validation engineers to ensure that a tagged release has been tested.
  49
  50
  51 LTS Release
  52 -----------
  53
  54 A stable release can be designated as an LTS release based on community
  55 agreement and a commitment from a maintainer. The current policy is that each
  56 year's November (X.11) release will be maintained as an LTS for 2 years.
  57
  58 After the X.11 release, an LTS branch will be created for it at
  59 https://git.dpdk.org/dpdk-stable where bugfixes will be backported to.
  60
  61 A LTS release may align with the declaration of a new major ABI version,
  62 please read the :doc:`abi_policy` for more information.
  63
  64 It is anticipated that there will be at least 3 releases per year of the LTS
  65 or approximately 1 every 4 months. This is done to align with the DPDK main
  66 branch releases so that fixes have already gone through validation as part of
  67 the DPDK main branch release validation. However, the cadence can be shorter or
  68 longer depending on the number and criticality of the backported
  69 fixes. Releases should be coordinated with the validation engineers to ensure
  70 that a tagged release has been tested.
  71
  72 For a list of the currently maintained stable/LTS branches please see
  73 the latest `stable roadmap <https://core.dpdk.org/roadmap/#stable>`_.
  74
  75 At the end of the 2 years, a final X.11.N release will be made and at that
  76 point the LTS branch will no longer be maintained with no further releases.
  77
  78
  79 What changes should be backported
  80 ---------------------------------
  81
  82 Backporting should be limited to bug fixes. All patches accepted on the main
  83 branch with a Fixes: tag should be backported to the relevant stable/LTS
  84 branches, unless the submitter indicates otherwise. If there are exceptions,
  85 they will be discussed on the mailing lists.
  86
  87 Fixes suitable for backport should have a ``Cc: stable@dpdk.org`` tag in the
  88 commit message body as follows::
  89
  90      doc: fix some parameter description
  91
  92      Update the docs, fixing description of some parameter.
  93
  94      Fixes: abcdefgh1234 ("doc: add some parameter")
  95      Cc: stable@dpdk.org
  96
  97      Signed-off-by: Alex Smith <alex.smith@example.com>
  98
  99
 100 Fixes not suitable for backport should not include the ``Cc: stable@dpdk.org`` tag.
 101
 102 To support the goal of stability and not introducing regressions,
 103 new code being introduced is limited to bug fixes.
 104 New features should not be backported to stable releases.
 105
 106 In some limited cases, it may be acceptable to backport a new feature
 107 to a stable release. Some of the factors which impact the decision by
 108 stable maintainers are as follows:
 109
 110 * Does the feature break API/ABI?
 111 * Does the feature break backwards compatibility?
 112 * Is it for the latest LTS release (to avoid LTS upgrade issues)?
 113 * Is there a commitment from the proposer or affiliation to validate the feature
 114   and check for regressions in related functionality?
 115 * Is there a track record of the proposer or affiliation validating stable releases?
 116 * Is it obvious that the feature will not impact existing functionality?
 117 * How intrusive is the code change?
 118 * What is the scope of the code change?
 119 * Does it impact common components or vendor specific?
 120 * Is there a justifiable use case (a clear user need)?
 121 * Is there a community consensus about the backport?
 122
 123 Performance improvements are generally not considered to be fixes,
 124 but may be considered in some cases where:
 125
 126 * It is fixing a performance regression that occurred previously.
 127 * An existing feature in LTS is not usable as intended without it.
 128
 129 The Stable Mailing List
 130 -----------------------
 131
 132 The Stable and LTS release are coordinated on the stable@dpdk.org mailing
 133 list.
 134
 135 All fix patches to the main branch that are candidates for backporting
 136 should also be CCed to the `stable@dpdk.org <https://mails.dpdk.org/listinfo/stable>`_
 137 mailing list.
 138
 139
 140 Releasing
 141 ---------
 142
 143 A Stable Release will be released by:
 144
 145 * Tagging the release with YY.MM.n (year, month, number).
 146 * Uploading a tarball of the release to dpdk.org.
 147 * Sending an announcement to the `announce@dpdk.org <https://mails.dpdk.org/listinfo/announce>`_
 148   list.
 149
 150 Stable releases are available on the `dpdk.org download page <https://core.dpdk.org/download/>`_.