| 1 | # Netdata Agent Versioning Policy (DRAFT) |
| 2 | |
| 3 | This document outlines how versions are handled for the Netdata Agent. This policy applies to version 2.0.0 of |
| 4 | the Netdata Agent and newer versions. |
| 5 | |
| 6 | ## Stable Releases |
| 7 | |
| 8 | Versions for stable releases of the Netdata Agent consist of three parts, a major version, a minor version, and |
| 9 | a patch version, presented like `<major>.<minor>.<patch>`. For example, a version of `1.42.3` has a major version |
| 10 | of 1, a minor version of 42, and a patch version of 3. |
| 11 | |
| 12 | The patch version is incremented when a new stable release is made that only contains bug fixes that do not alter |
| 13 | the public API in a backwards incompatible manner. Special exceptions may be made for critical security bugs, |
| 14 | but such exceptions will be prominently noted in the release notes for the versions for which they are made. |
| 15 | |
| 16 | The minor version is incremented when a new stable release is made that contains new features and functionality |
| 17 | that do not alter the strictly defined parts of public API in a backwards incompatible manner. A new minor version |
| 18 | may have changes to the loosely defined parts of the public API that are not backwards compatible, but unless |
| 19 | they are critical security fixes they will be announced ahead of time in the release notes for the previous minor |
| 20 | version. Once a new minor version is published, no new patch releases will be published for previous minor versions |
| 21 | unless they fix serious bugs. |
| 22 | |
| 23 | The major version is incremented when a new stable release is made that alters the strictly defined public API in |
| 24 | some backwards incompatible manner. Any backwards incompatible changes that will be included in a new major version |
| 25 | will be announced ahead of time in the release notes for the previous minor version. Once a given major version |
| 26 | is published, no new minor releases will be published for any prior major version, though new patch releases _may_ |
| 27 | be published for the latest minor release of any prior major version to fix serious bugs. |
| 28 | |
| 29 | In most cases, just prior to a new major version being published, a final stable minor release will be published |
| 30 | for the previous major version, including all non-breaking changes that will be in the new major version. This is |
| 31 | intended to ensure that users who choose to remain on the previous major version for an extended period of time |
| 32 | will be as up-to-date as possible. |
| 33 | |
| 34 | ## Nightly Builds |
| 35 | |
| 36 | Versions for nightly builds of the Netdata Agent consist of four parts, a major version, a minor version, a revision |
| 37 | number, and an optional commit ID, presented like `<major>.<minor>.0-<revision>-<commit>`. For example, a version |
| 38 | of `1.43.0-11-gb15437502` has a major version of 1, a minor version of 43, a revision of 11, and a commit ID of |
| 39 | `gb15437502`. A commit ID consists of a lowercase letter `g`, followed by the short commit hash for the corresponding |
| 40 | commit. If the commit ID is not included, it may be replaced by the word ‘nightly’. |
| 41 | |
| 42 | The major and minor version numbers for a nightly build correspond exactly to an associated stable release. A |
| 43 | given major version of a nightly build has the same compatibility guarantees as it would for a stable release. A |
| 44 | given minor version of a nightly build will generally include any backwards-incompatible changes to the loosely |
| 45 | defined public API that will be in the _next_ minor version of the associated stable release. |
| 46 | |
| 47 | The revision number indicates the number of commits on the main branch of the Netdata Agent git repository since |
| 48 | the associated stable release, and the commit ID, if included, should indicate the exact commit hash used for the |
| 49 | nightly build. |
| 50 | |
| 51 | Due to how our release process works, nightly version numbers do not track stable patch releases. For example, if the |
| 52 | latest stable release is `1.42.4`, the latest nightly version will still show something like `1.42.0-209-nightly`. The |
| 53 | first nightly build version published after an associated stable release will include all relevant fixes that were |
| 54 | in that stable release. In addition, in most cases, the last nightly build version published before an associated |
| 55 | stable patch release will include all relevant fixes that are in that patch release. |
| 56 | |
| 57 | Nightly builds are only published on days when changes have actually been committed to the main branch of the |
| 58 | Netdata Agent git repository. |
| 59 | |
| 60 | ## Public API |
| 61 | |
| 62 | The remainder of the document outlines the public API of the Netdata Agent. |
| 63 | |
| 64 | We define two categories of components within the public API: |
| 65 | |
| 66 | - Strictly defined components are guaranteed not to change in a backwards incompatible manner without an associated |
| 67 | major version bump, and will have impending changes announced in the release notes at least one minor release |
| 68 | before they are changed. |
| 69 | - Loosely defined components are guaranteed not to change in a backwards incompatible manner without an associated |
| 70 | minor version bump, and will have impending changes announced in the release notes at least one minor release |
| 71 | before they are changed. |
| 72 | |
| 73 | There are also a few things we handle specially, which will be noted later in the document. |
| 74 | |
| 75 | ### Strictly Defined Public API Components |
| 76 | |
| 77 | The following aspects of the public API are strictly defined, and are guaranteed not to change in a backwards |
| 78 | incompatible manner without an associated major version increase, and such changes will be announced in the release |
| 79 | notes at least one minor release prior to being merged: |
| 80 | |
| 81 | - All mandatory build dependencies which are not vendored in the Netdata Agent code. This includes, but is not |
| 82 | limited to: |
| 83 | - The underlying build system (such as autotools or CMake). |
| 84 | - Primary library dependencies (such as libuv). |
| 85 | - Any external tooling that is required at build time. |
| 86 | - The REST API provided by the Netdata Agent’s internal web server, accessible via the `/api` endpoint. This |
| 87 | does not extend to the charts, labels, or other system-specific data returned by some API endpoints. |
| 88 | - The protocol used for streaming and replicating data between Netdata Agents. |
| 89 | - The protocol used for communicating with external data collection plugins. |
| 90 | - The APIs provided by the `python.d.plugin` and `charts.d.plugin` data collection frameworks. |
| 91 | - The set of optional features supported by the Agent which are provided by default in our pre-built packages. If |
| 92 | support for an optional feature is being completely removed from the Agent, that is instead covered by what |
| 93 | component that feature is part of. |
| 94 | |
| 95 | ### Loosely Defined Public API Components |
| 96 | |
| 97 | The following aspects of the public API are loosely defined. They are guaranteed to not change in a backwards |
| 98 | incompatible manner without an associated minor version increase, and such changes will be announced in the release |
| 99 | notes at least one minor release prior to being merged: |
| 100 | |
| 101 | - Configuration options in any configuration file normally located under `/etc/netdata` on a typical install, |
| 102 | as well as their default values. |
| 103 | - Environment variables that are interpreted by the Netdata Agent, or by the startup code in our official OCI |
| 104 | container images. |
| 105 | - The exact set of charts provided, including chart families, chart names, and provided metrics. |
| 106 | - The exact set of supported data collection sources and data export targets. |
| 107 | - The exact set of system service managers we officially support running the Netdata Agent under. |
| 108 | - The exact set of alert delivery mechanisms supported by the Netdata Agent. |
| 109 | - The high-level implementation of the Netdata Agent’s integrated web server. |
| 110 | - The v0 and v1 dashboard UIs provided through the Netdata Agent’s internal web server. |
| 111 | |
| 112 | All loosely defined API components may also change in a backwards incompatible manner if the major version is |
| 113 | increased. Large scale changes to these components may also warrant a major version increase even if there are no |
| 114 | backwards incompatible changes to strictly defined public API components. |
| 115 | |
| 116 | ### Special Cases |
| 117 | |
| 118 | The following special exceptions to the public API exist: |
| 119 | |
| 120 | - When an internal on-disk file format (such as the dbengine data file format) is changed, the old format is |
| 121 | guaranteed to be supported for in-place updates for at least two minor versions after the change happens. The |
| 122 | new format is not guaranteed to be backwards compatible. |
| 123 | - The list of supported platforms is functionally a part of the public API, but our existing [platform support |
| 124 | policy](/packaging/PLATFORM_SUPPORT.md) dictates when and how |
| 125 | support for specific platforms is added or removed. |
| 126 | - The list of components provided as separate packages in our official native packages is considered part of our |
| 127 | strictly defined public API, but changes to our packaging that do not alter the functionality of existing installs |
| 128 | are considered to be backwards compatible. This means that we may choose to split a plugin out to it’s own |
| 129 | package at any time, but it will remain as a mandatory dependency until at least the next major release. |
| 130 | - Options and environment variables used by the `kickstart.sh` install script and the `netdata-updater.sh` script |
| 131 | are handled separately from regular Netdata Agent versioning. Backwards compatible changes may happen at any |
| 132 | time for these, while backwards incompatible changes will have a deprecation period during which the old behavior |
| 133 | will be preserved but will issue a warning about the impending change. |
| 134 | |
| 135 | ### Things Not Covered By The Public API |
| 136 | |
| 137 | Any components which are not explicitly listed above as being part of the public API are not part of the public |
| 138 | API. This includes, but is not limited to: |
| 139 | |
| 140 | - Any mandatory build components which are vendored as part of the Netdata sources, such as SQLite3 or libJudy. This |
| 141 | extends to both the presence or absence of such components, as well as the exact version being bundled. |
| 142 | - The exact installation mechanism that will be used on any given system when using our `kickstart.sh` installation |
| 143 | script. |
| 144 | - The exact underlying implementation of any data collection plugin. |
| 145 | - The exact underlying implementation of any data export mechanism. |