From 5f6b0f52d91faa9a008908b39ffcdbf700abe093 Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Mon, 25 Apr 2022 12:15:05 +0200 Subject: [PATCH 1/3] [docs] Added note on versioning --- docs/dev/developers-guide.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/dev/developers-guide.md b/docs/dev/developers-guide.md index 3084373e1..1de99c66d 100644 --- a/docs/dev/developers-guide.md +++ b/docs/dev/developers-guide.md @@ -121,6 +121,23 @@ The SRT installation has the following folders: * *test - unit tests for the library. * *testing - the folder contains applications used during development: `srt-test-live`, `srt-test-file`, etc. Use `-DENABLE_TESTING=ON` to include in the build. +## Versioning + +THe SRT library is versioned as `major.minor.patch`, e.g. v1.4.3. + +The patch version upgrade usually means improvements and/or bug fixes, that do not affect SRT API/ABI compatibility and do not significantly change the library behavior. Thus, an application can relatively safely update onto the next SRT patch release. + +Any minor version upgrade means SRT might be no longer fully compliant with the OLD API and/or old behavior or contains notable changes in the source code. +A certain amount of care should be taken considering the upgrade to the new minor release. A proper testnig should be done, and the review of changes. + +By default the SRT library SO/DLL name is suffixed with `major.minor` version (starting from SRT v1.4.3): +- `libsrt.so.1.4`-> `libsrt.so.1.4.3`. +- `libsrt.so.1.4`-> `libsrt.so.1.4.4` +- `libsrt.so.1.5`-> `libsrt.so.1.5.0` +- ... + +This way upgrading the app to the latest patch release is quite easy, while upgrading to the new minor release might require rebuilding certain modules of the solution. + ## Coding Rules TBD. From 719dce7aaad74a9dcf5c69c76b5038711b031d9e Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Mon, 25 Apr 2022 12:18:42 +0200 Subject: [PATCH 2/3] Fixed typos --- docs/dev/developers-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/developers-guide.md b/docs/dev/developers-guide.md index 1de99c66d..08b100f79 100644 --- a/docs/dev/developers-guide.md +++ b/docs/dev/developers-guide.md @@ -123,12 +123,12 @@ The SRT installation has the following folders: ## Versioning -THe SRT library is versioned as `major.minor.patch`, e.g. v1.4.3. +The SRT library is versioned as `major.minor.patch`, e.g. v1.4.3. The patch version upgrade usually means improvements and/or bug fixes, that do not affect SRT API/ABI compatibility and do not significantly change the library behavior. Thus, an application can relatively safely update onto the next SRT patch release. Any minor version upgrade means SRT might be no longer fully compliant with the OLD API and/or old behavior or contains notable changes in the source code. -A certain amount of care should be taken considering the upgrade to the new minor release. A proper testnig should be done, and the review of changes. +A certain amount of care should be taken considering the upgrade to the new minor release. A proper testing should be done, and the review of changes. By default the SRT library SO/DLL name is suffixed with `major.minor` version (starting from SRT v1.4.3): - `libsrt.so.1.4`-> `libsrt.so.1.4.3`. From cb56745a540ffb5dbf61d3f2b0f8b62e94963487 Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Thu, 28 Apr 2022 11:49:02 +0200 Subject: [PATCH 3/3] Update developers-guide.md --- docs/dev/developers-guide.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/dev/developers-guide.md b/docs/dev/developers-guide.md index 08b100f79..389beb57a 100644 --- a/docs/dev/developers-guide.md +++ b/docs/dev/developers-guide.md @@ -5,6 +5,7 @@ * [Forking SRT on GitHub](#forking-srt-on-github) * [Building SRT](#building-srt) * [Project Structure](#project-structure) +* [Versioning](#versioning) * [Coding Rules](#coding-rules) * [Submitting an Issue](#submitting-an-issue) * [Submitting a Pull Request](#submitting-a-pull-request) @@ -123,20 +124,28 @@ The SRT installation has the following folders: ## Versioning -The SRT library is versioned as `major.minor.patch`, e.g. v1.4.3. +The SRT library is versioned as `major.minor.patch`, e.g. v1.4.3. +Due to legacy reasons SRT library version also defines SRT protocol version, announced in the dedicated field of the handshake packet (see the Handshake section of the [SRT Internet Draft](https://datatracker.ietf.org/doc/html/draft-sharabayko-srt-01#section-3.2.1). -The patch version upgrade usually means improvements and/or bug fixes, that do not affect SRT API/ABI compatibility and do not significantly change the library behavior. Thus, an application can relatively safely update onto the next SRT patch release. +The patch version upgrade usually means improvements and/or bug fixes, that do not affect SRT [API/ABI compatibility](https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C++) and do not significantly change the library behavior. Thus, an application can relatively safely update onto the next SRT patch release. -Any minor version upgrade means SRT might be no longer fully compliant with the OLD API and/or old behavior or contains notable changes in the source code. -A certain amount of care should be taken considering the upgrade to the new minor release. A proper testing should be done, and the review of changes. +Any minor version upgrade means SRT might be no longer **fully** compliant with the OLD API/ABI and/or old behavior or contains notable changes in the source code. +A certain amount of care should be taken considering the upgrade to the new minor release. A proper testing should be done, and the review of changes listed in the release notes. -By default the SRT library SO/DLL name is suffixed with `major.minor` version (starting from SRT v1.4.3): +By default the SRT library `SO`/`DYLIB` name is suffixed with `major.minor` version (starting from SRT v1.4.3): - `libsrt.so.1.4`-> `libsrt.so.1.4.3`. - `libsrt.so.1.4`-> `libsrt.so.1.4.4` - `libsrt.so.1.5`-> `libsrt.so.1.5.0` - ... -This way upgrading the app to the latest patch release is quite easy, while upgrading to the new minor release might require rebuilding certain modules of the solution. +This way upgrading the app with dynamic SRT linking to the latest patch release is quite easy, while upgrading to the new minor release must happen with awareness and thus might require rebuilding certain modules of the solution. + +All SRT versions prior to SRT v1.4.3 had a single `SO`/`DYLIB` name `libsrt.so.1`, while ABI incompatibility could be broken. Thus it was not safe to perform wide deployment of different SRT library versions with the same ABI version: +- `libsrt.so.1`-> `libsrt.so.1.4.2`. +- `libsrt.so.1`-> `libsrt.so.1.3.4` +- `libsrt.so.1`-> `libsrt.so.1.3.0` +- ... + ## Coding Rules