@cryptotaxi247 / netdata-1 / commits / f0b8f079d

Add document outlining our versioning policy and public API. (#16227)

* Add document outlining our versioning policy and public API. * Assorted updates.

Austin S. Hemmelgarn committed Oct 26, 2023 at 07:02 UTC f0b8f079d808fb80ef0f2145e236e07f89bf7b4e
1 file changed +129
packaging/VERSIONING_AND_PUBLIC_API.md new
+129
@@ -0,0 +1,129 @@
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 lowercaase 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 major version bump, and will have impending changes announced in the release notes at least one minor release before they are changed.
67 +- Loosely defined components are guaranteed not to change in a backwards incompatible manner without an associated minor version bump, and will have impending changes announced in the release notes at least one minor release before they are changed.
68 +
69 +There are also a few things we handle specially, which will be noted later in the document.
70 +
71 +### Strictly Defined Public API Components
72 +
73 +The following aspects of the public API are strictly defined, and are guaranteed not to change in a backwards incompatible manner without an associated major version increase, and such changes will be announced in the release notes at least one minor release prior to being merged:
74 +
75 +- All mandatory build dependencies which are not vendored in the Netdata Agent code. This includes, but is not
76 + limited to:
77 + - The underlying build system (such as autotools or CMake).
78 + - Primary library dependencies (such as libuv).
79 + - Any external tooling that is required at build time.
80 +- The REST API provided by the Netdata Agent’s internal web server, accessible via the `/api` endpoint. This
81 + does not extend to the charts, labels, or other system-specific data returned by some API endpoints.
82 +- The protocol used for streaming and replicating data between Netdata Agents.
83 +- The set of features provided by default in our pre-built packages.
84 +
85 +### Loosely Defined Public API Components
86 +
87 +The following aspects of the public API are loosely defined. They are guaranteed to not change in a backwards
88 +incompatible manner without an associated minor version increase, and such changes will be announced in the release
89 +notes at least one minor release prior to being merged:
90 +
91 +- Configuration options in any configuration file normally located under `/etc/netdata` on a typical install.
92 +- Environment variables that are interpreted by the Netdata Agent, or by the startup code in our official OCI
93 + container images.
94 +- The exact set of charts provided, including chart families, chart names, and provided metrics.
95 +- The exact set of supported data collection sources and data export targets.
96 +- The exact set of system service managers we officially support running the Netdata Agent under.
97 +- The high-level implementation of the Netdata Agent’s integrated web server.
98 +- The v0 and v1 dashboard UIs provided through the Netdata Agent’s internal web server.
99 +
100 +### Special Cases
101 +
102 +The following special exceptions to the public API exist:
103 +
104 +- When an internal on-disk file format (such as the dbengine data file format) is changed, the old format is
105 + guaranteed to be supported for in-place updates for at least two minor versions after the change happens. The
106 + new format is not guaranteed to be backwards compatible.
107 +- The list of supported platforms is functionally a part of the public API, but our existing [platform support
108 + policy](https://github.com/netdata/netdata/blob/master/packaging/PLATFORM_SUPPORT.md) dictates when and how
109 + support for specific platforms is added or removed.
110 +- The list of components provided as separate packages in our official native packages is considered part of our
111 + strictly defined public API, but changes to our packaging that do not alter the functionality of existing installs
112 + are considered to be backwards compatible. This means that we may choose to split a plugin out to it’s own
113 + package at any time, but it will remain as a mandatory dependency until at least the next major release.
114 +- Options and environment variables used by the `kickstart.sh` install script and the `netdata-updater.sh` script
115 + are handled separately from regular Netdata Agent versioning. Backwards compatible changes may happen at any
116 + time for these, while backwards incompatible changes will have a deprecation period during which the old behavior
117 + will be preserved but will issue a warning about the impending change.
118 +
119 +### Things Not Covered By The Public API
120 +
121 +Any components which are not explicitly listed above as being part of the public API are not part of the public
122 +API. This includes, but is not limited to:
123 +
124 +- Any mandatory build components which are vendored as part of the Netdata sources, such as SQLite3 or libJudy. This
125 + extends to both the presence or abscence of such components, as well as the exact version being bundled.
126 +- The exact installation mechanism that will be used on any given system when using our `kickstart.sh` installation
127 + script.
128 +- The exact underlying implementation of any data collection plugin.
129 +- The exact underlying implementation of any data export mechanism.