Merge branch 'main' into FlattenLearningCurve_and_AddVisualStudio

Author: GVskl

.env.example

@@ -0,0 +1,10 @@
+# Copy this file to .env and fill in the values.
+# .env is gitignored and will never be committed or affect the published site.
+
+# Option 1: Skip all GitHub API calls entirely (fastest local builds, no contributor/commit data).
+SKIP_CONTRIBUTORS=true
+
+# Option 2: Use a GitHub Personal Access Token (PAT) for full local builds with real data.
+# Generate one at https://github.com/settings/tokens (read:public_repo scope is enough).
+# Comment out SKIP_CONTRIBUTORS above and uncomment the line below.
+# ACCESS_TOKEN=ghp_your_personal_access_token_here

.nuke/build.schema.json

@@ -31,7 +31,8 @@
         "Deploy",
         "PullDnnPackages",
         "Restore",
-        "Serve"
+        "Serve",
+        "ValidateGitHubToken"
       ]
     },
     "Verbosity": {
@@ -117,6 +118,11 @@
           "type": "string",
           "description": "Github Token"
         },
+        "Port": {
+          "type": "integer",
+          "description": "Port to serve the docs on locally (default: 8085, auto-increments if already in use)",
+          "format": "int32"
+        },
         "Solution": {
           "type": "string",
           "description": "Path to a solution file that is automatically loaded"

README.md

@@ -38,6 +38,25 @@ Unless you are part of the DNNDocs core team, you will only have read access (yo
 ### .NET Framework Prerequisites
 You should ensure that you already have [.NET 5.0](https://dotnet.microsoft.com/download/dotnet) (used by the `build` project) and the "Developer Pack" for [.NET Framework 4.6.2](https://dotnet.microsoft.com/download/dotnet-framework/net462) (used by the custom `DocFx` plugins) installed on your machine before trying the build process.
 
+### Environment Variables
+
+The build uses a `.env` file in the root of the repository for local configuration. This file is gitignored so it will never be committed. Copy `.env.example` to get started:
+
+```
+copy .env.example .env
+```
+
+Open `.env` and choose one of two modes:
+
+| Mode | When to use |
+|------|-------------|
+| `SKIP_CONTRIBUTORS=true` | **Recommended for most contributors.** Skips all GitHub API calls, making local builds much faster. Contributor and last-updated data will be absent from the local preview. |
+| `ACCESS_TOKEN=ghp_...` | Use when you need to verify contributor/commit data locally. Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens) with `read:public_repo` scope. |
+
+> **Note:** Without a token and without `SKIP_CONTRIBUTORS=true`, the build will still work but may be slow or hit the GitHub anonymous rate limit.
+
+### Running the build
+
 You should now be able to run the development version of the docs locally with the following command:
 
 Windows Powershell:
@@ -71,6 +90,12 @@ First, it is recommended to create a new branch to collect your changes without
 git checkout -b your-branch-name
 ```
 
+If you made some changes before making a branch (you are on branch **main** and it's dirty), you can switch+create like this:
+
+```
+git switch -c your-branch-name
+```
+
 Next you can start editing documentation and saving files using your favorite text editor (Visual Studio Code, Atom, Sublime Text, Brackets/Phoenix Code, Notepad++, etc). When you are done with your changes you can verify the modified files. Some code editors will actually show a status of the modified files in their UI. If you want to verify it using the command line you can run the following command:
 
 ```

build/Build.cs

@@ -1,5 +1,10 @@
 using System;
 using System.Linq;
+using System.Net;
+using System.Net.Http;
+using System.Net.Http.Headers;
+using System.Net.Sockets;
+using System.Threading.Tasks;
 using Nuke.Common;
 using Nuke.Common.CI.GitHubActions;
 using Nuke.Common.IO;
@@ -53,6 +58,9 @@ class Build : NukeBuild
     [Parameter("Github Token")]
     readonly string GithubToken;
 
+    [Parameter("Port to serve the docs on locally (default: 8085, auto-increments if already in use)")]
+    readonly int Port = 8085;
+
     // Nuke features injection.
     [Solution] readonly Solution Solution;
     [GitRepository] readonly GitRepository gitRepository;
@@ -132,12 +140,86 @@ class Build : NukeBuild
         });
 
     Target Serve => _ => _
+        .DependsOn(ValidateGitHubToken)
         .DependsOn(Clean)
         .DependsOn(Restore)
         .DependsOn(BuildPlugins)
         .Executes(() =>
         {
-            DnnDocFX?.Invoke("--serve --open-browser", RootDirectory);
+            DnnDocFX?.Invoke($"--serve --open-browser --port {FindFreePort(Port)}", RootDirectory);
+        });
+
+    static int FindFreePort(int startPort)
+    {
+        for (var port = startPort; port < startPort + 20; port++)
+        {
+            try
+            {
+                var listener = new TcpListener(IPAddress.Loopback, port);
+                listener.Start();
+                listener.Stop();
+                return port;
+            }
+            catch (SocketException) { }
+        }
+        throw new Exception($"Could not find a free port in range {startPort}-{startPort + 19}.");
+    }
+
+    Target ValidateGitHubToken => _ => _
+        .Executes(async () =>
+        {
+            // Load .env file manually (DotNetEnv is not a build project dependency)
+            var envFile = RootDirectory / ".env";
+            if (envFile.FileExists())
+            {
+                foreach (var line in System.IO.File.ReadAllLines(envFile))
+                {
+                    if (string.IsNullOrWhiteSpace(line) || line.TrimStart().StartsWith("#")) continue;
+                    var parts = line.Split('=', 2);
+                    if (parts.Length == 2)
+                        Environment.SetEnvironmentVariable(parts[0].Trim(), parts[1].Trim());
+                }
+            }
+
+            var token = Environment.GetEnvironmentVariable("ACCESS_TOKEN");
+            if (string.IsNullOrEmpty(token))
+                token = GithubToken;
+
+            if (string.IsNullOrEmpty(token))
+            {
+                Serilog.Log.Warning("No GitHub token found. Contributor and commit data will be skipped.");
+                Serilog.Log.Warning("To enable it, set ACCESS_TOKEN in your .env file (see .env.example).");
+                Environment.SetEnvironmentVariable("SKIP_CONTRIBUTORS", "true");
+                return;
+            }
+
+            using var http = new HttpClient();
+            http.DefaultRequestHeaders.UserAgent.Add(new ProductInfoHeaderValue("DNNDocs-Build", "1.0"));
+            http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
+
+            var response = await http.GetAsync("https://api.github.com/user");
+
+            if (response.StatusCode == HttpStatusCode.Unauthorized)
+                Assert.Fail("GitHub token is invalid or has expired. Generate a new one at https://github.com/settings/tokens");
+
+            if (!response.IsSuccessStatusCode)
+                Assert.Fail($"GitHub token validation returned an unexpected status: {(int)response.StatusCode} {response.ReasonPhrase}");
+
+            // Check that the token has the required scope
+            response.Headers.TryGetValues("X-OAuth-Scopes", out var scopeValues);
+            var scopes = (scopeValues?.FirstOrDefault() ?? string.Empty)
+                .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+
+            if (scopes.Length > 0 && !scopes.Contains("public_repo") && !scopes.Contains("repo"))
+                Assert.Fail($"GitHub token is missing the 'public_repo' scope. Current scopes: {string.Join(", ", scopes)}. " +
+                    "Regenerate it at https://github.com/settings/tokens");
+
+            var login = await response.Content.ReadAsStringAsync();
+            var loginStart = login.IndexOf("\"login\":\"") + 9;
+            var loginEnd = login.IndexOf('"', loginStart);
+            var username = loginStart > 8 ? login[loginStart..loginEnd] : "unknown";
+
+            Serilog.Log.Information("GitHub token is valid. Authenticated as: {Username}", username);
         });
 
     Target CreateDeployBranch => _ => _
@@ -151,6 +233,7 @@ class Build : NukeBuild
 
     Target Deploy => _ => _
         .OnlyWhenDynamic(() => gitRepository.ToString() == $"https://github.com/{organizationName}/{repositoryName}")
+        .DependsOn(ValidateGitHubToken)
         .DependsOn(CreateDeployBranch)
         .DependsOn(Compile)
         .Executes(() => {

content/getting-started/setup/upgrades/post-10.2.0-steps.md

@@ -18,7 +18,7 @@ Before starting the upgrade process, it is recommended to have a very clear unde
 
 * Know the [suggested upgrade path](xref:setup-upgrades-suggested-upgrade-path) and take the necessary planning steps to make each of these upgrade steps for the best success.
 
-* Download the appropriate "Upgrade" ZIP package for your upgrade from [the official repository on GitHub](https://github.com/dnnsoftware/DNN.Platform/releases). The file can be found in the **Assets** section for the desired version release and will have a naming convention like **DNN_Platform_10.2.1_Upgrade.zip**.
+* Download the appropriate "Install" ZIP package for your upgrade from [the official repository on GitHub](https://github.com/dnnsoftware/DNN.Platform/releases). The file can be found in the **Assets** section for the desired version release and will have a naming convention like **DNN_Platform_10.3.2_Install.zip**. According to the new upgrade process, upgrade packages will no longer be required.
 
 * Know any changes to the minimum requirements for the desired version of DNN Platform and plan for implementation accordingly. 
 
@@ -45,8 +45,8 @@ If this level of access to the server is not possible, there are other options d
 
 ## Step 3 - Upload Upgrade Package
 Login as a SuperUser (Host) and navigate to: Settings => Servers => System Info => Upgrades.
-Click on "Upload Package" and upload the previously downloaded upgrade zip file.
-The system will validate the upgrade package and warn about potential issues if detected.
+Click on "Upload Package" and upload the previously downloaded zip file.
+The system will validate the install package and warn about potential issues if detected.
 
 ## Step 4 - Initiate Upgrade
 If the uploaded file is valid, it will be listed and have a "steps" button. Clicking that button will perform any special upgrade steps that DNN may require and then show the upgrade page where you can again login as a SuperUser to start the auto-upgrade process.

content/getting-started/setup/upgrades/suggested-upgrade-path/index.md

@@ -15,8 +15,8 @@ The below is, of course, subject to change. If your current version of DNN Platf
 
 | **FROM Version** | **TO Version** | **Notes** |
 |---|---|---|
-| [10.02.04] | [10.03.01] | * DNN 10.2.0 introduced a new simplified upgrade process, see [Post-10.2.0 Upgrade Guide](xref:setup-upgrades-post-10.2.0).<br /><br /> * DNN 10.2.3 has an issue with uploading upgrades, if upgrading from 10.2.3, please upload your next version package to `App_Data\Upgrade` folder manually.<br /><br /> |
-| [09.13.09] | [10.02.04] | * DNN 10.0.0 is a significant release with both [Breaking Changes and New Features][bc-10], it also introduced minimum requirements for ASP.NET 4.8 and SQL Server 2017. In addition, it will force-remove DNN-Provided Telerik versions.<br /><br /> * DNN 10.1.1 new installs use SHA256 as the default password hashing algorithm. This only affects new installs, if you want to migrate an upgraded site to SHA256, please read [the documentation for membership provider changes](xref:security-membership-providers).<br /><br /> |
+| [10.02.05] | [10.03.02] | * DNN 10.2.0 introduced a new simplified upgrade process, see [Post-10.2.0 Upgrade Guide](xref:setup-upgrades-post-10.2.0).<br /><br /> * DNN 10.2.3 has an issue with uploading upgrades, if upgrading from 10.2.3, please upload your next version package to `App_Data\Upgrade` folder manually.<br /><br /> |
+| [09.13.09] | [10.02.05] | * DNN 10.0.0 is a significant release with both [Breaking Changes and New Features][bc-10], it also introduced minimum requirements for ASP.NET 4.8 and SQL Server 2017. In addition, it will force-remove DNN-Provided Telerik versions.<br /><br /> * DNN 10.1.1 new installs use SHA256 as the default password hashing algorithm. This only affects new installs, if you want to migrate an upgraded site to SHA256, please read [the documentation for membership provider changes](xref:security-membership-providers).<br /><br /> |
 | [09.03.02] | [09.13.09] | * DNN 9.4.0 introduced a minimum requirement of ASP.NET 4.7.2.<br /><br /> * DNN 9.8.0 (and above for the 9.x series releases) brings the OPTIONAL (but HIGHLY RECOMMENDED) [Telerik Removal](xref:setup-telerik-removal).<br /><br /> |
 | [09.01.01] | [09.03.02] | * DNN 9.2.0 multiple APIs were removed that were marked deprecated in DNN 7 and before. Most of the core modules have been updated since and you can find them at [dnncommunity][dnncommunity-gh].<br /><br /> * If you have other modules installed, please check for updates before upgrading to DNN 9.2.0 or later.<br /><br /> |
 | [08.00.04] | [09.01.01] | |
@@ -34,8 +34,8 @@ The below is, of course, subject to change. If your current version of DNN Platf
 | [02.00.04] | [02.01.02] | |
 
 <!-- Version links (DNN Platform releases) -->
-[10.03.01]: https://github.com/dnnsoftware/Dnn.Platform/releases/tag/v10.3.1
-[10.02.04]: https://github.com/dnnsoftware/Dnn.Platform/releases/tag/v10.2.4
+[10.03.02]: https://github.com/dnnsoftware/Dnn.Platform/releases/tag/v10.3.2
+[10.02.05]: https://github.com/dnnsoftware/Dnn.Platform/releases/tag/v10.2.5
 [09.13.09]: https://github.com/dnnsoftware/Dnn.Platform/releases/tag/v9.13.9
 [09.03.02]: https://github.com/dnnsoftware/Dnn.Platform/releases/tag/v9.3.2
 [09.01.01]: https://github.com/dnnsoftware/Dnn.Platform/releases/tag/v9.1.1