Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Add information about the preview tag #19949

Merged
merged 1 commit into from
Feb 25, 2025
Merged

doc: Add information about the preview tag #19949

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 30 additions & 31 deletions doc/nrf/dev_model_and_contributions/code_base.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,28 +151,31 @@ The |NCS| version numbers are assigned based on very specific criteria.
They follow the ``MAJOR.MINOR.PATCH`` pattern (also further called as ``X.Y.Z``), with possible additional postfixes depending on the release.
All releases are accompanied by their respective :ref:`release_notes`.

+----------------------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| Release type | Release criteria | Comments |
+============================+============================================================================+======================================================================================================================================+
| ``MAJOR`` | Introduces a large number of substantial changes across the board | Major version number is increased rarely. |
| | | Major releases are always accompanied by a :ref:`migration guide <migration_guides>`. |
+----------------------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``MINOR`` | Introduces one or more new functionalities. | Version number is increased every time a minor release is cut. |
| | | Minor releases are the default types of an |NCS| release and usually are accompanied by a :ref:`migration guide <migration_guides>`. |
| | | The new functionalities may break existing APIs. |
+----------------------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``PATCH`` | Introduces bugfixes or minor changes to the existing functionalities. | Patch releases only address functional issues and do not introduce new functionalities. |
| | | Patch releases do not come with :ref:`migration guide <migration_guides>`. |
+----------------------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``MAJOR.MINOR.99`` | The ``99`` added at the end of the version number indicates | The number can be used between minor, major, or patch releases. |
| | that the version string is a point in between two releases. | |
| | Such version does not belong to a release and corresponds to the | |
| | current state of development. | |
+----------------------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``MAJOR.MINOR.PATCH-devN`` | Development tag, marked through a postfix added to the end of the version. | Not part of the regular release cycle. |
| | Indicates a snapshot of the development state that is created to highlight | The ``-devN`` version might not be subjected to the same amount of testing as a regular |NCS| release. |
| | the introduction of a new piece of functionality. | |
+----------------------------+----------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+--------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| Version | Description |
+================================+======================================================================================================================================+
| ``MAJOR`` | Introduces a large number of substantial changes across the board. |
| | Major version number is increased rarely. |
| | Major releases are always accompanied by a :ref:`migration guide <migration_guides>`. |
+--------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``MINOR`` | Introduces one or more new functionalities. |
| | Version number is increased every time a minor release is cut. |
| | Minor releases are the default types of an |NCS| release and usually are accompanied by a :ref:`migration guide <migration_guides>`. |
| | The new functionalities may break existing APIs. |
+--------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``PATCH`` | Introduces bug fixes or minor changes to the existing functionalities. |
| | Patch releases only address functional issues and do not introduce new functionalities. |
| | Patch releases do not come with :ref:`migration guide <migration_guides>`. |
+--------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``MAJOR.MINOR.99`` | The ``99`` added at the end of the version number indicates that the version string is a point in between two releases. |
| | Such version does not belong to a release and corresponds to the current state of development. |
| | The number can be used between minor, major, or patch releases. |
+--------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``MAJOR.MINOR.PATCH-previewN`` | A preview of one or more new functionalities. |
| | A preview tag is recommended for development for users who are in the initial phase of product development |
| | and need to add new features of the |NCS|. |
| | The ``-previewN`` version is verified using automated test suites only. |
+--------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+

There are two fundamental revisions that are relevant to most |NCS| users:

Expand All @@ -199,19 +202,15 @@ A release candidate postfix ``-rcN`` can be optionally attached if the tag ident

The Git tags are composed as follows::

vX.Y.Z(-rcN|-devN)
vX.Y.Z(-rcN|-previewN)

Tags without a suffix correspond to official releases tested and signed by Nordic Semiconductor engineers.
A release candidate suffix ``-rcN`` is attached if the tag identifies a candidate instead of the actual release.

.. dev_tag_definition_start

In between releases, there might be development tags.
These are identified by a ``-devN`` suffix included after the |NCS| version, for example ``v1.9.99-dev1`` for the main branch or ``v1.9.2-dev1`` for the release branch.
Such versions indicate a snapshot of the development state that is created to highlight the introduction of a new piece of functionality.
Unlike an |NCS| release, a ``-devN`` version may or may not have received the same amount of testing.

.. dev_tag_definition_end
In between releases, there might be development tags, called preview tags.
These are identified by a ``-previewN`` suffix included after the |NCS| version, for example ``v2.8.0-preview1``.
Such versions are recommended for development for users who are in the initial phase of product development and need to add new features of the |NCS|.
Unlike an |NCS| release, a ``-previewN`` version version is verified using automated test suites only.

In the case of OSS repositories, the git tag format reuses the upstream project's version along with some |NCS| specific postfixes::

Expand Down
8 changes: 4 additions & 4 deletions doc/nrf/installation/install_ncs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,8 +210,8 @@ Simply put, you can work with the following versions of the |NCS|:
* - Specific release (recommended)
- Release tag (for example, |release_tt|)
- :ref:`Release_notes` of the release
* - :ref:`Development tag <dm-revisions>`
- Development tag (for example, ``v1.9.2-dev1``)
* - :ref:`Preview tag <dm-revisions>`
- Development tag (for example, ``v2.8.0-preview1``)
- :ref:`Changelog <release_notes>` of the tag
* - Branch
- Branch name (for example, ``main``)
Expand Down Expand Up @@ -296,11 +296,11 @@ For more information about the repository and development model, see the :ref:`d

west init -m https\://github.com/nrfconnect/sdk-nrf --mr |release| |release|

* **Development tag:** To check out the ``v1.9.2-dev1`` tag, enter the following command:
* **Preview tag:** To check out the ``v2.8.0-preview1`` tag, enter the following command:

.. code-block:: console

west init -m https://github.com/nrfconnect/sdk-nrf --mr v1.9.2-dev1 v1.9.2-dev1
west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.8.0-preview1

* **Branch**: To check out the ``main`` branch that includes the latest state of development, enter the following command:

Expand Down
1 change: 1 addition & 0 deletions doc/nrf/releases_and_maturity/release_notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ This page is included only in the latest documentation, because it might contain
releases/release-notes-2.9.0-nRF54H20-1-rc2
releases/release-notes-2.9.0
releases/release-notes-2.8.0
releases/release-notes-2.8.0-preview1
releases/release-notes-2.7.99-cs2
releases/release-notes-2.7.99-cs1
releases/release-notes-2.7.0
Expand Down
Loading