From 07fcfbca4b2d3343347a90fe1b0bbb8b86f3bc91 Mon Sep 17 00:00:00 2001 From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com> Date: Wed, 19 Nov 2025 22:45:01 -0500 Subject: [PATCH 1/4] Add mgversion json configuration file --- mgversion.json | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 mgversion.json diff --git a/mgversion.json b/mgversion.json new file mode 100644 index 00000000..84ce2d54 --- /dev/null +++ b/mgversion.json @@ -0,0 +1,4 @@ +{ + "mgVersion": "3.8.4.1", + "mgDevelopVersion": "3.8.5-develop.13" +} \ No newline at end of file From 77b5c8e2293754932c5646fadf883d1323e7754f Mon Sep 17 00:00:00 2001 From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com> Date: Wed, 19 Nov 2025 22:45:14 -0500 Subject: [PATCH 2/4] Update docfx json configuration files to import the mgversion configuration file --- ci.docfx.json | 1 + docfx.json | 1 + 2 files changed, 2 insertions(+) diff --git a/ci.docfx.json b/ci.docfx.json index 1fc4b077..39ed2af0 100644 --- a/ci.docfx.json +++ b/ci.docfx.json @@ -59,6 +59,7 @@ } ], "output": "_site", + "globalMetadataFiles": ["mgversion.json"], "globalMetadata": { "_appLogoUrl": "https://monogame.net", "_appFaviconPath": "/images/favicon.png", diff --git a/docfx.json b/docfx.json index 36d1fa7d..b3fb74bf 100644 --- a/docfx.json +++ b/docfx.json @@ -59,6 +59,7 @@ } ], "output": "_site", + "globalMetadataFiles": ["mgversion.json"], "globalMetadata": { "_appLogoUrl": "https://monogame.net", "_appFaviconPath": "/images/favicon.png", From f0cb9f734eef6ee278baf5dc965506183f1d3d8d Mon Sep 17 00:00:00 2001 From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com> Date: Wed, 19 Nov 2025 22:45:22 -0500 Subject: [PATCH 3/4] Update post transform to replace mgversion tokens with global version number --- templates/monogame/conceptual.extension.js | 30 ++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/templates/monogame/conceptual.extension.js b/templates/monogame/conceptual.extension.js index fa9aa775..3e05d236 100644 --- a/templates/monogame/conceptual.extension.js +++ b/templates/monogame/conceptual.extension.js @@ -66,5 +66,35 @@ function slugify(value) { * This method will be called at the end of exports.transform in conceptual.html.primary.js */ exports.postTransform = function (model) { + applyMonoGameVersion(model); return model; } + +function applyMonoGameVersion(model) { + if (model.mgVersion) { + replaceInModel(model, '{{mgVersion}}', model.mgVersion); + } + + if (model.mgDevelopVersion) { + replaceInModel(model, '{{mgDevelopVersion}}', model.mgDevelopVersion) + } +} + + +function replaceInModel(model, token, value) { + if (model.conceptual) { + model.conceptual = model.conceptual.split(token).join(value); + } + + if (model.title) { + model.title = model.title.split(token).join(value); + } + + if (model.rawTitle) { + model.rawTitle = model.rawTitle.split(token).join(value); + } + + if (model.description) { + model.description = model.description.split(token).join(value); + } +} \ No newline at end of file From 74b2c66e4ceff62ed909cf769cdd0c0817d8fd83 Mon Sep 17 00:00:00 2001 From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com> Date: Wed, 19 Nov 2025 22:45:29 -0500 Subject: [PATCH 4/4] Update instances in documentation where version number should always reflect current version --- ..._setting_up_your_os_for_development_arch.md | 2 +- ...setting_up_your_os_for_development_macos.md | 2 +- ...etting_up_your_os_for_development_ubuntu.md | 2 +- ...tting_up_your_os_for_development_windows.md | 2 +- .../howto/HowTo_Install_Preview_Release.md | 18 +++++++++--------- articles/migration/migrate_38.md | 18 +++++++++--------- articles/migration/updating_versions.md | 2 +- 7 files changed, 23 insertions(+), 23 deletions(-) diff --git a/articles/getting_started/1_setting_up_your_os_for_development_arch.md b/articles/getting_started/1_setting_up_your_os_for_development_arch.md index fc51e312..42d6ad98 100644 --- a/articles/getting_started/1_setting_up_your_os_for_development_arch.md +++ b/articles/getting_started/1_setting_up_your_os_for_development_arch.md @@ -6,7 +6,7 @@ description: This section provides a step-by-step guide for setting up your deve > [!TIP] > Arch Linux is a rolling release distribution. This guide was tested in October 2025 with kernel `version 6.15.9-arch1-1`. -To develop with MonoGame in C#, you will need to install the .NET 9 SDK. As of MonoGame 3.8.4.1 the recommended version is .NET 9. +To develop with MonoGame in C#, you will need to install the .NET 9 SDK. As of MonoGame {{mgVersion}} the recommended version is .NET 9. > [!TIP] > You can still continue to use .NET 8 if you wish, you will just need to downgrade your client project .NET version in the `csproj` setup for your project (if using the default templates) diff --git a/articles/getting_started/1_setting_up_your_os_for_development_macos.md b/articles/getting_started/1_setting_up_your_os_for_development_macos.md index ef488c61..149a1e12 100644 --- a/articles/getting_started/1_setting_up_your_os_for_development_macos.md +++ b/articles/getting_started/1_setting_up_your_os_for_development_macos.md @@ -3,7 +3,7 @@ title: Setting up your OS for development on MacOS description: This section provides a step-by-step guide for setting up your development environment on Mac. --- -To develop with MonoGame in C#, you will need to install the .NET SDK. As of MonoGame 3.8.4.1 the recommended version is .NET 9. +To develop with MonoGame in C#, you will need to install the .NET SDK. As of MonoGame {{mgVersion}} the recommended version is .NET 9. > [!TIP] > You can still continue to use .NET 8 if you wish, you will just need to downgrade your client project .NET version in the `csproj` setup for your project (if using the default templates) diff --git a/articles/getting_started/1_setting_up_your_os_for_development_ubuntu.md b/articles/getting_started/1_setting_up_your_os_for_development_ubuntu.md index 96481c49..7f437820 100644 --- a/articles/getting_started/1_setting_up_your_os_for_development_ubuntu.md +++ b/articles/getting_started/1_setting_up_your_os_for_development_ubuntu.md @@ -6,7 +6,7 @@ description: This section provides a step-by-step guide for setting up your deve > [!TIP] > The minimum version of Ubuntu that is supported by MonoGame is `20.04`. -To develop with MonoGame in C#, you will need to install the .NET SDK. As of MonoGame 3.8.4.1 the minimum supported version is .NET 9. +To develop with MonoGame in C#, you will need to install the .NET SDK. As of MonoGame {{mgVersion}} the minimum supported version is .NET 9. ## Install .NET 9 SDK diff --git a/articles/getting_started/1_setting_up_your_os_for_development_windows.md b/articles/getting_started/1_setting_up_your_os_for_development_windows.md index 877fa5f7..1cf000d0 100644 --- a/articles/getting_started/1_setting_up_your_os_for_development_windows.md +++ b/articles/getting_started/1_setting_up_your_os_for_development_windows.md @@ -3,7 +3,7 @@ title: Setting up your OS for development on Windows description: This section provides a step-by-step guide for setting up your development environment on Windows. --- -To develop with MonoGame in C#, you must install the .NET SDK. As of MonoGame 3.8.4.1 the minimum supported version is .NET 9. +To develop with MonoGame in C#, you must install the .NET SDK. As of MonoGame {{mgVersion}} the minimum supported version is .NET 9. > [!IMPORTANT] > If your chosen IDE for development is [Visual Studio](https://visualstudio.microsoft.com/) then you can skip this step as .NET 8 is included with the Visual Studio Installer. diff --git a/articles/getting_to_know/howto/HowTo_Install_Preview_Release.md b/articles/getting_to_know/howto/HowTo_Install_Preview_Release.md index 6c006f61..1997c25d 100644 --- a/articles/getting_to_know/howto/HowTo_Install_Preview_Release.md +++ b/articles/getting_to_know/howto/HowTo_Install_Preview_Release.md @@ -24,8 +24,8 @@ To use the preview packages delivered via NuGet you need to update or replace yo The simplest way is from the command line in the folder where your `csproj` is located (if you have multiple projects, please repeat for each) using the following syntax: ```dotnetcli -dotnet add package MonoGame.Framework.DesktopGL -v 3.8.4-preview.1 -dotnet add package MonoGame.Content.Builder.Task -v 3.8.4-preview.1 +dotnet add package MonoGame.Framework.DesktopGL -v {{mgDevelopVersion}} +dotnet add package MonoGame.Content.Builder.Task -v {{mgDevelopVersion}} ``` **Replacing the preview version with the specific version you wish to install.** @@ -42,11 +42,11 @@ To ensure symmetry between the project version and the Content Pipeline Editor ( This is simply a matter of updating the tools references, again from the command line in the projects folder, as follows: ```dotnetcli -dotnet tool install dotnet-mgcb --version 3.8.4-preview.1 -dotnet tool install dotnet-mgcb-editor --version 3.8.4-preview.1 -dotnet tool install dotnet-mgcb-editor-linux --version 3.8.4-preview.1 -dotnet tool install dotnet-mgcb-editor-windows --version 3.8.4-preview.1 -dotnet tool install dotnet-mgcb-editor-mac --version 3.8.4-preview.1 +dotnet tool install dotnet-mgcb --version {{mgDevelopVersion}} +dotnet tool install dotnet-mgcb-editor --version {{mgDevelopVersion}} +dotnet tool install dotnet-mgcb-editor-linux --version {{mgDevelopVersion}} +dotnet tool install dotnet-mgcb-editor-windows --version {{mgDevelopVersion}} +dotnet tool install dotnet-mgcb-editor-mac --version {{mgDevelopVersion}} ``` **Replacing the preview version with the specific version you wish to install.** @@ -65,7 +65,7 @@ This step is optional, if you intend to generate a new project using the latest 1. Simply run the following from the command line: ```dotnetcli -dotnet new install MonoGame.Templates.CSharp::3.8.4-preview.1 +dotnet new install MonoGame.Templates.CSharp::{{mgDevelopVersion}} ``` **Replacing the preview version of MonoGame at the end of the command with the specific version you wish to install.** @@ -77,7 +77,7 @@ At this time, the Visual Studio marketplace does not support preview versions of The Extension can be downloaded from the latest `GitHub Actions` build used to generate the preview build. 1. Go to the [MonoGame GitHub repository](https://github.com/MonoGame/MonoGame/actions) and select the "Actions" tab. -1. Find the build with the associated tag, e.g. [`v3.8.4-preview.1`](https://github.com/MonoGame/MonoGame/actions/runs/14713318149) +1. Find the build with the associated tag, e.g. [`{{mgDevelopVersion}}`](https://github.com/MonoGame/MonoGame/actions/runs/14713318149) 1. In the `Artifacts` for the build, you should see the extensions installer `MonoGame.Templates.VSExtension.vsix` 1. Click on the "Download Icon" on the far right-hand side of the row. 1. Once downloaded, run the `vsix` which will update your installation of the extensions package. diff --git a/articles/migration/migrate_38.md b/articles/migration/migrate_38.md index d7b56217..0382cbcd 100644 --- a/articles/migration/migrate_38.md +++ b/articles/migration/migrate_38.md @@ -1,6 +1,6 @@ --- title: Upgrading MonoGame from 3.8.x to latest -description: A guide on upgrading a MonoGame v3.8 project to the current 3.8.4.1+ releases of MonoGame. +description: A guide on upgrading a MonoGame v3.8 project to the current {{mgVersion}}+ releases of MonoGame. --- Upgrading existing projects from earlier 3.8 releases should be straightforward for most platforms. @@ -10,7 +10,7 @@ Upgrading existing projects from earlier 3.8 releases should be straightforward - The critical difference from pre 3.8.2 builds, [is that the MGCB Editor is no longer a global .NET tool](#addupdate-dotnet-toolsjson-configuration) and the MGCB editor is now included as part of the specific project through the use of the dotnet tooling configuration `dotnet-tools.json` file located in the `.config` folder in your solution/project. -- The major difference from 3.8.4 onwards is that we recommend using .NET 9 in your client project, but it is not mandatory, we are also simplifying the `csproj` configuration to reduce management for developers from 3.8.4.1. +- The major difference from {{mgVersion}} onwards is that we recommend using .NET 9 in your client project, but it is not mandatory, we are also simplifying the `csproj` configuration to reduce management for developers from {{mgVersion}}. > For iOS/Android however, DotNet 9 at a minimum is Mandatory, [see details here](#iosipados-and-android-considerations). @@ -58,8 +58,8 @@ Make sure you update the MonoGame references to the latest version, this can be - Use the [Updating NuGet package dependencies](../getting_to_know/howto/HowTo_Install_Preview_Release.md#updating-nuget-package-dependencies) documentation as part of the "Preview Release installation instructions", which states you should run the following commands (the example is for `DesktopGL`, use other platforms accordingly): ```dotnetcli - dotnet add package MonoGame.Framework.DesktopGL -v 3.8.4.1 - dotnet add package MonoGame.Content.Builder.Task -v 3.8.4.1 + dotnet add package MonoGame.Framework.DesktopGL -v {{mgVersion}} + dotnet add package MonoGame.Content.Builder.Task -v {{mgVersion}} ``` > [!NOTE] @@ -95,31 +95,31 @@ or alternatively you can do the following: "isRoot": true, "tools": { "dotnet-mgcb": { - "version": "3.8.4.1", + "version": "{{mgVersion}}", "commands": [ "mgcb" ] }, "dotnet-mgcb-editor": { - "version": "3.8.4.1", + "version": "{{mgVersion}}", "commands": [ "mgcb-editor" ] }, "dotnet-mgcb-editor-linux": { - "version": "3.8.4.1", + "version": "{{mgVersion}}", "commands": [ "mgcb-editor-linux" ] }, "dotnet-mgcb-editor-windows": { - "version": "3.8.4.1", + "version": "{{mgVersion}}", "commands": [ "mgcb-editor-windows" ] }, "dotnet-mgcb-editor-mac": { - "version": "3.8.4.1", + "version": "{{mgVersion}}", "commands": [ "mgcb-editor-mac" ] diff --git a/articles/migration/updating_versions.md b/articles/migration/updating_versions.md index 12605e04..3b1ed8cf 100644 --- a/articles/migration/updating_versions.md +++ b/articles/migration/updating_versions.md @@ -62,7 +62,7 @@ dotnet restore Regardless of the development environment, users will need to update the dotnet tools manifest file manually to use the newest version of the *MonoGame Content Builder*. To do this: 1. Open the *.config/dotnet-tools.json* manifest file located in the project root directory -2. Update the version specified for each tool to the current version of MonoGame (currently this is `3.8.4`). +2. Update the version specified for each tool to the current version of MonoGame (currently this is `{{mgVersion}}`). 3. Save the changes Once these changes are made, open a command prompt or terminal at the root of the project directory and enter the following commands