From a94eebe08f166207ac7a1999a7fd40d2ead59d70 Mon Sep 17 00:00:00 2001 From: kpal Date: Mon, 30 Jun 2025 18:15:50 +0100 Subject: [PATCH 1/5] Added page on engine versioning --- docs/user-manual/engine/versioning.md | 30 +++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/user-manual/engine/versioning.md diff --git a/docs/user-manual/engine/versioning.md b/docs/user-manual/engine/versioning.md new file mode 100644 index 00000000000..055eed53b7a --- /dev/null +++ b/docs/user-manual/engine/versioning.md @@ -0,0 +1,30 @@ +--- +title: Semantic Versioning +sidebar_position: 3 +--- + +The engine supports both prereleases and releases. This page outlines the hierarchy of each version type and what they represent. + +### `alpha` (not implemented yet) + +An alpha prerelease is the most unstable type of release purely for testing features in a branch for a PR. This is useful for mobile debugging and profiling new ideas without having to deploy a full release. + +### `beta` + +A beta prerelease represents all the latest features that have been approved from the PR stage and have been merged into `main` the main development branch. These features have been initially tested but not gone through a more thorough testing process like for an official minor release. This is useful if you have some new API you want to take advantage for in other projects but do not want to build the engine from source as a submodule. + +### `preview` + +A preview prerelease is the last type of prerelease which contains all the latest features or breaking changes prior to a minor release or bug fixes prior to a patch release. This is useful for testing large and complex projects in the Editor and additionally mobile testing and profiling. + +### `patch` + +This is the smallest type of release which contains **non-breaking** changes to the engine. This will exclude any API changes or new features - only bug fixes. The Editor will only show the latest patch version for any particular minor release. + +### `minor` + +This release contains all new features and additions to the engine API along with deprecations and breaking changes. The Editor supports both the latest minor and the previous minor to allow for migrations in API to occur across larger projects. + +### `major` + +This type of release is reserved for large changes or additions to the engine API. A recent example of such was the addition of full WebGPU support and the removal of WebGL 1.0 support moving from v1.x.x to v2.x.x. \ No newline at end of file From cbf1c0498108300a98e4165f781943e6265f20a1 Mon Sep 17 00:00:00 2001 From: kpal Date: Mon, 30 Jun 2025 18:18:10 +0100 Subject: [PATCH 2/5] Lint fix --- docs/user-manual/engine/versioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-manual/engine/versioning.md b/docs/user-manual/engine/versioning.md index 055eed53b7a..517903d4a78 100644 --- a/docs/user-manual/engine/versioning.md +++ b/docs/user-manual/engine/versioning.md @@ -23,8 +23,8 @@ This is the smallest type of release which contains **non-breaking** changes to ### `minor` -This release contains all new features and additions to the engine API along with deprecations and breaking changes. The Editor supports both the latest minor and the previous minor to allow for migrations in API to occur across larger projects. +This release contains all new features and additions to the engine API along with deprecations and breaking changes. The Editor supports both the latest minor and the previous minor to allow for migrations in API to occur across larger projects. ### `major` -This type of release is reserved for large changes or additions to the engine API. A recent example of such was the addition of full WebGPU support and the removal of WebGL 1.0 support moving from v1.x.x to v2.x.x. \ No newline at end of file +This type of release is reserved for large changes or additions to the engine API. A recent example of such was the addition of full WebGPU support and the removal of WebGL 1.0 support moving from v1.x.x to v2.x.x. From fb82bea2153520d0191d99234965deadb79438cd Mon Sep 17 00:00:00 2001 From: kpal Date: Tue, 1 Jul 2025 12:19:26 +0100 Subject: [PATCH 3/5] Commented alpha prerelease section in versioning documentation --- docs/user-manual/engine/versioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-manual/engine/versioning.md b/docs/user-manual/engine/versioning.md index 517903d4a78..ef40f3f2a3c 100644 --- a/docs/user-manual/engine/versioning.md +++ b/docs/user-manual/engine/versioning.md @@ -5,9 +5,9 @@ sidebar_position: 3 The engine supports both prereleases and releases. This page outlines the hierarchy of each version type and what they represent. -### `alpha` (not implemented yet) + ### `beta` From c12a845c8d15ed5a34a9a335780e0a9e078d6cd8 Mon Sep 17 00:00:00 2001 From: kpal Date: Tue, 1 Jul 2025 12:46:15 +0100 Subject: [PATCH 4/5] Rewrote minor and patch to indicate we follow semver and. mention we have occasional breaking changes in minor releases --- docs/user-manual/engine/versioning.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/user-manual/engine/versioning.md b/docs/user-manual/engine/versioning.md index ef40f3f2a3c..1b9c97ad667 100644 --- a/docs/user-manual/engine/versioning.md +++ b/docs/user-manual/engine/versioning.md @@ -19,11 +19,17 @@ A preview prerelease is the last type of prerelease which contains all the lates ### `patch` -This is the smallest type of release which contains **non-breaking** changes to the engine. This will exclude any API changes or new features - only bug fixes. The Editor will only show the latest patch version for any particular minor release. +This is the smallest type of release following [semantic versioning](https://semver.org/). The Editor will only show the latest patch version for any particular minor release. ### `minor` -This release contains all new features and additions to the engine API along with deprecations and breaking changes. The Editor supports both the latest minor and the previous minor to allow for migrations in API to occur across larger projects. +This type of release follows the standard outlined by [semantic versioning](https://semver.org/). Occasionally we may have **breaking changes in minor releases** but these are rare and will be notified of in advance. As such the Editor supports both the latest minor and the previous minor to allow for migrations in API to occur across larger projects. + +:::important + +If you are using the engine with NPM it is recommended to use the `~X.X.X` notation to pin the major and minor version numbers and only update to the latest patch + +::: ### `major` From 723715c4b2a5ca6fea240e0668a42949027f263e Mon Sep 17 00:00:00 2001 From: kpal Date: Tue, 1 Jul 2025 12:49:49 +0100 Subject: [PATCH 5/5] Fix punctuation in NPM usage recommendation in versioning documentation --- docs/user-manual/engine/versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-manual/engine/versioning.md b/docs/user-manual/engine/versioning.md index 1b9c97ad667..5fb3c30e2c0 100644 --- a/docs/user-manual/engine/versioning.md +++ b/docs/user-manual/engine/versioning.md @@ -27,7 +27,7 @@ This type of release follows the standard outlined by [semantic versioning](http :::important -If you are using the engine with NPM it is recommended to use the `~X.X.X` notation to pin the major and minor version numbers and only update to the latest patch +If you are using the engine with NPM it is recommended to use the `~X.X.X` notation to pin the major and minor version numbers and only update to the latest patch. :::