diff --git a/guides/o3de-deprecation-guidelines.md b/guides/o3de-deprecation-guidelines.md index b150680..54e8fa3 100644 --- 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 new file mode 100644 index 0000000..86f8852 --- /dev/null +++ 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 `` 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. +