Add version guidance to API deprecation guidelines (#196)

* Add version guidance to API deprecation guidelines Signed-off-by: Alex Peterson <[email protected]> * Added version guidelines Signed-off-by: Alex Peterson <[email protected]> * Addressing excellent feedback Signed-off-by: alexpete <[email protected]> --------- Signed-off-by: Alex Peterson <[email protected]> Signed-off-by: alexpete <[email protected]>
o3de · May 10, 2023 · f89e99d · f89e99d
1 parent 02b857f
commit f89e99d
Show file tree

Hide file tree

Showing 2 changed files with 76 additions and 0 deletions.
diff --git a/guides/o3de-deprecation-guidelines.md b/guides/o3de-deprecation-guidelines.md
@@ -20,6 +20,19 @@
 
 An overview of how to make breaking API changes/removals.
 
+In the ideal case, API deprecation would happen over 2 O3DE releases which typically happen every 6 months.
+1. In the first release an `O3DE_DEPRECATION_NOTICE` is added, so developers know API code is being deprecated, but it doesn't cause the compile warnings/errors that `AZ_DEPRECATED` does.
+2. In the second release `version` fields are updated and `AZ_DEPRECATED` macros are added, causing code compile warnings for all developers using the methods that can be ignored with compiler flags.
+3. After the second release, the code is removed and won't exist in the third release.
+
+In real life it's often not practical for developers to babysit deprecated code over a year or longer.  At minimum, developers should: 
+1. Add the `O3DE_DEPRECATION_NOTICE` code comment (see below), so the change can be easily found and added to release notes.
+1. Increment the `MAJOR` and zero out the remaining elements in the `version` field in the `gem.json` if inside a gem or `engine.json` if  inside the engine's `Code` folder.  
+
+Developers rely on the `version` field to catch `MAJOR` compatibility changes that make their code no longer compile.  For more information about how versioning is used in O3DE see the [Engine Versioning](https://www.o3de.org/docs/contributing/release-versioning-and-terms/) and [Gem Versioning](https://www.o3de.org/docs/user-guide/gems/gem-versioning/) documentation.
+
+Related RFC: [Engine, Project and Gem Versions](https://github.com/o3de/sig-core/issues/44)
+
 ### API Deprecation - Examples
 
 - Renaming a function
@@ -45,6 +58,7 @@ An overview of how to make breaking API changes/removals.
     // O3DE_DEPRECATION_NOTICE(GHI-1234)
     AZ::Entity* CreateEditorEntity(const char* name) = 0;
     ```
+    - *Note: If you are replacing an API method with new methods, consider incrementing the MINOR version number in the `gem.json` or engine API you are updating so any developers who depend on the API can reference the new version at the point when the new API methods became available.*
 
 3. Create a pull request referencing the GitHub issue. Code owners will be notified of this change. (Check the [CODEOWNERS](https://github.com/o3de/o3de/blob/development/.github/CODEOWNERS) file to verify which sig the deprecation applies to).
 
@@ -62,6 +76,14 @@ An overview of how to make breaking API changes/removals.
   - It is required to first use the comment identifier `O3DE_DEPRECATION_NOTICE`, and as a second pass, add `AZ_DEPRECATED` (applies to mature APIs - see [Stable vs Volatile APIs](#stable-vs-volatile-apis)).
   - Note: In C++ code, `@deprecated` may be used to highlight deprecation changes in the API reference. This is not widely supported and is not a requirement at this time.
 
+### API Deprecation - Final Steps
+
+After the `O3DE_DEPRECATION_NOTICE` comment has been present in the code for one O3DE release (typically 6 months):
+1. Add the `AZ_DEPRECATED` macro to the API methods.
+2. Increment the `MAJOR` element and zero out the other elements in the `version` field in the `gem.json` if gem code or `engine.json` if engine code.
+
+After the `AZ_DEPRECATED` macro has been present in the code for one release, remove the code.
+
 ## System/Feature Deprecation
 
 An overview of how to make breaking System/Feature changes/removals.

diff --git a/guides/o3de-version-guidelines.md b/guides/o3de-version-guidelines.md
@@ -0,0 +1,54 @@
+# O3DE Version Guide
+
+> **Process Owner**: sig-core
+
+Related RFC: [Engine, Project and Gem Versions](https://github.com/o3de/sig-core/issues/44)
+
+For more information about how versioning is used in O3DE see the [Engine Versioning](https://www.o3de.org/docs/contributing/release-versioning-and-terms/) and [Gem Versioning](https://www.o3de.org/docs/user-guide/gems/gem-versioning/) documentation.
+
+## O3DE Version Numbering
+
+O3DE uses `MAJOR.MINOR.PATCH` [semantic versioning](https://semver.org/)  for all the version fields in `engine.json`, `gem.json` and `project.json` files.
+
+- `MAJOR` is for API-breaking changes
+- `MINOR` is for non-API-breaking changes that add new APIs or change them in a non-breaking way
+- `PATCH` is for all other non-API-breaking changes, usually important fixes
+
+Example: If a breaking API change is made to a gem at version `2.0.1` the `MAJOR` version is incremented and the `MINOR` and `PATCH` are reset to 0 resulting in the new version being `3.0.0`. See the [semantic versioning](https://semver.org/) page for more examples.
+
+## O3DE Version Specifiers 
+
+Lists of compatible engines and dependencies use the `<name><version specifier>` format based on [PEP 440](https://peps.python.org/pep-0440/#version-specifiers).
+
+Examples:
+
+| Name | Version Specifier | Combined | Description |
+|------|-------------------|----------|-------------|
+| o3de | >=2.0.0           | o3de>=2.0.0 | o3de version 2.0.0 or greater |
+| o3de-sdk | == 1.2.0      | o3de-sdk==1.2.0 |  o3de-sdk version 1.2.0 | 
+| Atom | ~=2.0.0           | Atom~=2.0.0 | Atom version 2.0.0 up to but not including 3.0.0 |
+
+A gem that is known to be compatible with an engine named `o3de-sdk` version `2.0.1` could include `o3de-sdk==2.0.1` in the `compatible_engines` field in `gem.json`
+
+## Guidelines for the `engine.json` '`version`' field 
+
+### API changes
+
+When you make a change to a `version` field in a `gem.json` file or `engine.json` `api_versions` entry, you should make the same change to the `version` field in `engine.json`.  This provides an overall indication that some important API change has been made in O3DE.  Ideally, this process will be automated, but is not critical.
+
+Example:
+
+A developer increments the `MINOR` version of the `Atom` `gem.json` and resets the `PATCH` version, the developer also should increment the `MINOR` version and reset the `PATCH` version to zero for the `version` field in `engine.json`
+
+Changes: 
+1. `gem.json` version `2.3.1` -> `2.4.0`
+2. `engine.json` version `15.3.2` -> `15.4.0` 
+
+### Stabilization processes
+
+When a new `stabilization/XXYY` branch is created the following changes should be made:
+1. Increment the `MINOR` version and reset the `PATCH` version to '0' in `engine.json` in the new `stabilization/XXYY` branch.
+2. Increment the `MAJOR` version and reset the `MINOR` and `PATCH` versions to '0' in `engine.json` in the `development` branch.
+
+These changes are made to prevent O3DE from having two branches with the same version.
+