additions and clarifications on semver

src/en/clean-copy/01-Introduction/05.md

@@ -1,11 +1,14 @@
 ### On Versioning
 
-Here and throughout we firmly stick to [semver](https://semver.org/) principles of versioning:
+Here and throughout we firmly stick to [semver](https://semver.org/) principles of versioning.
+
   1. API versions are denoted with three numbers, i.e. `1.2.3`.
-  1. First number (major version) increases when backwards-incompatible changes in the API are shipped.
-  2. Second number (minor version) increases when new functionality is added to the API, keeping backwards compatibility intact.
-  3. Third number (patch) increases when a new API version contains bug fixes only.
+  1. The first number (a major version) increases when backwards-incompatible changes in the API are introduced.
+  2. The second number (a minor version) increases when new functionality is added to the API, keeping backwards compatibility intact.
+  3. The third number (a patch) increases when a new API version contains bug fixes only.
 
 Sentences ‘major API version’ and ‘new API version, containing backwards-incompatible changes’ are therefore to be considered equivalent ones.
 
-In Section II we will discuss versioning policies in more detail. In Section I, we will just use semver versions designation, specifically `v1`, `v2`, etc.
+It is usually (though not necessary) agreed that the last stable API version might be referenced by either a full version (e.g. `1.2.3`) or a reduced one (`1.2` or just `1`). Some systems support more sophisticated schemes of defining the desired version (for example, `^1.2.3` reads like ‘get the last stable API version that is backwards-compatible to the `1.2.3` version’) or additional shortcuts (for example, `1.2-beta` to refer to the last beta-version of the `1.2` API version family). In this book, we will mostly use designations like `v1` (`v2`, `v3`, etc.) to denote the latest stable release of the `1.x.x` version family of an API.
+
+The practical meaning of this versioning system and the applicable policies will be discussed in more detail in the ‘Backwards Compatibility Problem Statement’ chapter.

src/en/clean-copy/03-Section II. The Backwards Compatibility/01.md

@@ -97,3 +97,21 @@ Let's briefly describe these decisions and the key factors for making them.
         * if you provide code-on-demand SDKs, it is considered a good form to provide an access to previous minor versions of SDK for a period of time sufficient enough for developers to test their application and fix some issues if necessary. Since full rewriting isn't necessary, it's fine to align with apps release cycle duration in your industry, which is usually several months in worst cases.
 
 We will address these questions in more detail in the next chapters. Additionally, in Section III we will also discuss, how to communicate to customers about new releases and discontinued supporting of older versions, and how to stimulate them to adopt new API versions.
+
+#### Simultaneous access to several API versions
+
+In modern professional software development, especially if we talk about internal APIs, a new API version usually fully replaces the previous one. If some problems are found, it might be rolled back (by releasing the previous version), but the two builds never co-exist. However, in the case of public APIs, the more the number of partner integrations is, the more dangerous this approach becomes.
+
+Indeed, with the growth of the number of users, the ‘rollback the API version in case of problems’ paradigm becomes increasingly destructive. To a partner, the optimal solution is rigidly referencing the specific API version — the one that had been tested (ideally, at the same time having the API vendor somehow seamlessly fixing security issues and making their software compliant with newly introduced legislation).
+
+**NB**. From the same considerations, providing beta (or maybe even alpha) versions of the popular APIs becomes more and more desirable as well, to make partners test the upcoming version and address the possible issues in advance.
+
+The important (and undeniable) advantage of the *semver* system is that it provides the proper version granularity:
+
+  * stating the first digit (major version) allows for getting a backwards-compatible version of the API;
+  * stating two digits (major and minor versions) allows to guarantee that some functionality that was added after the initial release will be available;
+  * finally, stating all three numbers (major version, minor version, and patch) allows for fixing a concrete API release with all its specificities (and errors), which — theoretically — means that the integration will remain operable till this version is physically available.
+
+Of course, preserving minor versions infinitely isn't possible (partly because of security and compliance issues that tend to pile up). However, providing such access for a reasonable period of time is rather a hygienic norm for popular APIs.
+
+**NB**. Sometimes to defend the single accessible API version concept, the following argument is put forward: preserving the SDK or API application server code is not enough to maintain strict backwards compatibility, as it might be relying on some un-versioned services (for example, some data in the DB that are shared between all the API versions). We, however, consider this an additional reason to isolate such dependencies (see ‘The Serenity Notepad’ chapter) as it means that changes to these subsystems might lead to the inoperability of the API.

src/en/clean-copy/04-Section III. The API Product/08.md

@@ -72,4 +72,4 @@ Usually, you can put forward some requirements for self-identifying of partners,
 
       All this leads to a situation when public APIs (especially those installed on free-to-use sites and applications) are very limited in the means of collecting the statistics and analyzing user behavior. And that impacts not only fighting all kinds of fraud but analyzing use cases as well. That's the way.
 
-**NB**. In some jurisdictions, IP addresses are considered personal data, and collecting them is prohibited as well. We don't dare to advise on how an API vendor might at the same time be able to fight prohibited content on the platform and don't have access to users' IP addresses. We presume that complying with such legislature implies storing statistics by IP address hashes. (And just in case we won't mention that building a rainbow table for SHA-256 hashes covering the entire 4-billion range of IPv4 addresses would take several hours on a regular office-grade computer.)
+**NB**. In some jurisdictions, IP addresses are considered personal data, and collecting them is prohibited as well. We don't dare to advise on how an API vendor might at the same time be able to fight prohibited content on the platform and don't have access to users' IP addresses. We presume that complying with such legislation implies storing statistics by IP address hashes. (And just in case we won't mention that building a rainbow table for SHA-256 hashes covering the entire 4-billion range of IPv4 addresses would take several hours on a regular office-grade computer.)

src/ru/clean-copy/01-Введение/05.md

@@ -1,6 +1,6 @@
 ### О версионировании
 
-Здесь и далее мы будем придерживаться принципов версионирования [semver](https://semver.org/):
+Здесь и далее мы будем придерживаться принципов версионирования [semver](https://semver.org/).
 
   1. Версия API задаётся тремя цифрами вида `1.2.3`.
   2. Первая цифра (мажорная версия) увеличивается при обратно несовместимых изменениях в API.
@@ -9,4 +9,6 @@
 
 Выражения «мажорная версия API» и «версия API, содержащая обратно несовместимые изменения функциональности» тем самым следует считать эквивалентными.
 
-Более подробно о политиках версионирования будет рассказано в разделе II. В разделе I мы ограничимся лишь указанием версии API в формате `v1`, `v2`, etc.
+Обычно (но не обязательно) устанавливается, что на последнюю стабильную версию API можно сослаться как по полной версии (`1.2.3`), так и по усечённой (`1.2` или просто `1`). Некоторые системы поддерживают и более сложные схемы указания подключаемой версии (например, `^1.2.3` читается как «подключить последнюю стабильную версию, обратно совместимую с версией `1.2.3`) или дополнительные шорткаты (например `1.2-beta` для подключения бета-версии API семейства `1.2`). В настоящей книге мы будем в основном использовать обозначения вида `v1` (`v2`, `v3` и так далее) для обозначения последнего стабильного релиза API семейства `1.x.x`.
+
+Более подробно о смысле и политиках такого версионирования читайте в главе «Постановка проблемы обратной совместимости».

src/ru/clean-copy/03-Раздел II. Обратная совместимость/01.md

@@ -98,3 +98,20 @@
 
 Дополнительно в разделе III мы также обсудим, каким образом предупреждать потребителей о выходе новых версий и прекращении поддержки старых, и как стимулировать их переходить на новые версии API.
 
+#### Одновременный доступ к нескольким минорным версиям API
+
+В современной промышленной разработке, особенно если мы говорим о внутренних API, новая версия, как правило, полностью заменяет предыдущую. Если в новой версии обнаруживаются критические ошибки, она может быть откачена (путём релиза предыдущей версии), но одновременно две сборки не сосуществуют. В случае публичных API такой подход становится тем более опасным, чем больше партнёров используют API.
+
+В самом деле, с ростом количества потребителей подход «откатить проблемную версию API в случае массовых жалоб» становится всё более деструктивным. Для партнёров, вообще говоря, оптимальным вариантом является жёсткая фиксация той версии API, для которой функциональность приложения была протестирована (и чтобы поставщик API при этом как-то незаметно исправлял возможные проблемы с информационной безопасностью и приводил своё ПО в соответствие с вновь возникающими законами).
+
+**NB**. Из тех же соображений следует, что для популярных API также становится всё более желательным предоставление возможности подключать бета-, а может быть и альфа-версии для того, чтобы у партнёров была возможность заранее понять, какие проблемы ожидают их с релизом новой версии API.
+
+Несомненный и очень важный плюс semver состоит в том, что она предоставляет возможность подключать версии с нужной гранулярностью:
+
+  * указание первой цифры (мажорной версии) позволяет гарантировать получение обратно совместимой версии API;
+  * указание двух цифр (минорной и мажорной версий) позволяет получить не просто обратно совместимую версию, но и необходимую функциональность, которая была добавлена уже после начального релиза;
+  * наконец, указание всех трёх цифр (мажорной, минорной и патча) позволяет жёстко зафиксировать конкретный релиз API, со всеми возможными особенностями (и ошибками) в его работе, что — теоретически — означает, что работоспособность интеграции не будет нарушена, пока эта версия физически доступна.
+
+Понятно, что бесконечное сохранение минорных версий в большинстве случаев невозможно (в т.ч. из-за накапливающихся проблем с безопасностью и соответствием законодательству), однако предоставление такого доступа в течение разумного времени для больших API является гигиенической нормой.
+
+**NB**. Часто в защиту политики только одной доступной версии API можно услышать аргумент о том, что кодом SDK или сервера API проблема обратной совместимости не исчерпывается, т.к. он может опираться на какие-то неверсионируемые сервисы (например, на какие-то данные в БД, которые должны разделяться между всеми версиями API) или другие API, придерживающиеся менее строгих политик. Это соображение, на самом деле, является лишь дополнительным аргументом в пользу изоляции таких зависимостей (см. главу «Блокнот душевного покоя»), поскольку это означает только лишь то, что изменения в этих подсистемах могут привести к неработоспособности API сами по себе.