docs: Information about supported versions (#1032)

README.md

@@ -11,6 +11,25 @@ The Box Java SDK for interacting with the
 ## Latest Release
 Latest release can be found [here](https://github.com/box/box-java-sdk/tree/v3.1.1).
 
+## Versions
+We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. See [version strategy](VERSIONS.md) for details which is effective from 30 July 2022.
+
+### Supported Version
+
+Only the current MAJOR version of SDK is supported. New features, functionality, bug fixes, and security updates will only be added to the current MAJOR version.
+
+A current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features.  Instead of stating a release date for a new feature, we set a fixed minor or patch release cadence of maximum 2-3 months (while we may release more often). At the same time, there is no schedule for major or breaking release. Instead, we will communicate one quarter in advance the upcoming breaking change to allow customers to plan for the upgrade. We always recommend that all users run the latest available minor release for whatever major version is in use. We highly recommend upgrading to the latest SDK major release at the earliest convenient time and before the EOL date.
+
+### Version schedule
+
+| Version | Current Patch/Minor | Supported Environments                                  | State     | First Release | EOL/Terminated |
+|---------|---------------------|---------------------------------------------------------|-----------|---------------|----------------|
+| 3       | 3.1.1               | Java 8 and up                                           | Supported | 17 Jan 2022   | TBD            |
+| 2       | 2.58.0              |                                                         | EOL       | 07 Jan 2016   | 17 Jan 2022    |
+| 1       | 1.1.0               |                                                         | EOL       | 15 Apr 2015   | 07 Jan 2016    |
+
+
+
 ## Getting Started
 Getting Started Docs: https://developer.box.com/guides/tooling/sdks/java/
 API Reference: https://developer.box.com/reference/

VERSIONS.md

@@ -0,0 +1,23 @@
+# Version Lifecycle
+We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. It is strongly encouraged that you pin at least the major version and potentially the minor version to avoid pulling in breaking changes.  Increasing the major version of an SDK indicates that this SDK underwent significant and substantial changes to support new idioms and patterns in the language. Major versions are introduced when public interfaces (e.g. classes, methods, types, etc.), behaviours, or semantics have changed. 
+
+Semantic Versions take the form of `MAJOR.MINOR.PATCH`.
+
+When bugs are fixed in the library in a backwards-compatible way, the PATCH level will be incremented by one. PATCH changes should not break your code and are generally safe for upgrade.
+
+When a new feature set comes online or a small breaking change is introduced, the MINOR version will be incremented by one and the PATCH version resets to zero. MINOR changes may require some amount of manual code change for upgrade. These backwards-incompatible changes will mostly be limited to a small number of function signature changes.
+
+The MAJOR version is used to indicate the family of technology represented by the library. Breaking changes that require extensive reworking of code will cause the MAJOR version to be incremented by one, and the MINOR and PATCH versions will be reset to zero. Since frequent major updates can be very disruptive, we will only introduce this type of breaking change when absolutely necessary.
+
+New MAJOR versions will be communicated in advance via:
+
+* An email announcement is sent to affected accounts, announcing our plans to end support for the specific SDK version. The email will outline the path to end-of-support, specify the campaign timelines, and provide upgrade guidance.
+* Box SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications.
+* Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the SDK documentation.
+
+Deprecations are introduced in minor releases. We will not introduce new deprecations in patch releases. These deprecations will preserve the existing behaviour while emitting a warning that provide guidance on:
+
+* How to achieve similar behaviour if an alternative is available
+* The version in which the deprecation will be enforced.
+
+Deprecations will only be enforced in major releases. For example, if a behaviour is deprecated in version 1.2.0, it will continue to work, with a warning, for all releases in the 1.x series. The behaviour will change and the deprecation will be removed in the next major release (2.x.x).