Merge pull request #3574 from dnnsoftware/release/9.5.0

Release/9.5.0

.github/BUILD.md

@@ -1,37 +1,131 @@
 # Building Dnn
 
-You do not always need to build the entire solution, you can download and install from the releases and only build the part you are working on, please read [How to Contribue](CONTRIBUTING.md) first.
+Important: **Dnn.Platform does not support "Hit F5 and see your website come up".** I.e. you can't run DNN by hitting F5 on the source code in Visual Studio.
 
-If you do need to build the entire solution and the distribution packages, you need to be aware that the entire distribution is split in multiple github repositories.
-* This repository - contains all the core APIs and the Admin Experience (Persona Bar)
+There are three supported build scenarios:
+1. **Build to create a platform distribution package**. You'd only use this to test a complete package (how it installs, works, etc). This build process is used by our Continuous Integration system and creates the release packages everyone uses to install the platform.
+2. **Build to create a local DNN development website**. You'd typically not do this all the time, but only when you wish to set up a new development site or revert your development website to the current DNN repository state.
+3. **Debug build**. You'd use this when changing code and testing your changes on your (previously created) development site. Note you can also "rebuild" just a part of the platform and not the entire solution for this which will speed things up for you.
+
+When contributing to DNN, you'd typically go through steps 2 and 3 at least and maybe 1 if you wish to run more encompassing tests. But before you delve into code, please familiarize yourself with [How to Contribute](CONTRIBUTING.md) first.
+
+## External sources
+
+There are two projects not included in this repository that are distributed with DNN:
 * [CKEditorProvider](https://github.com/DNN-Connect/CKEditorProvider) - The default HTML Editor Provider
 * [CDF](https://github.com/dnnsoftware/ClientDependency) - The Dnn Client Dependency Framework
 
-Also, we currently maintain two branches, the development branch is the next major release and we also maintain a release/x.x.x branch that allows doing bug fixes on the current major version.
+If you wish to make changes to those, please keep this in mind.
 
-To prevent issues with long paths in some build scripts, fork this repository in a short named folder on the root of any drive such as `c:\dnnsrc\` if you fork to a long path such as `c:\users\username\documents\dnn\source\` you may encounter long path issues.
+## Used Build Technologies
+
+DNN uses the following technologies to create a working build:
+1. MSBuild. This is Microsoft Visual Studio's built in mechanism to compile C#. It can also run auxiliary tasks (like packaging the included modules). These tasks are specified in `.build` and `.targets` files and can leverage .net assemblies to do its magic. Almost all central MSBuild code is in the `Build/BuildScripts` folder. Main folder location settings can be found in the `DNN_Platform.build` file in the root of the repository which can be overridden using a `DNN_Platform.local.build` file at the same location.
+2. Webpack. The "Admin Experience" (which is the project that contains the UI for managing DNN) contains a number of client-side Javascript projects (mostly React projects). These are built using Webpack. Webpack is triggered in the main build process in the `Build/BuildScripts/AEModule.build` script. But it can be run on individual projects if you need to.
+3. [Cake Build](https://cakebuild.net/). This uses C# code to run build tasks. We use Cake for orchestrating the entire build process (e.g. packaging of the platform) and for auxiliary tasks like creating a dev site. All Cake scripts are found in the `Build/Cake` folder. After Cake first runs it bootstraps itself and creates the `tools` folder where the various assemblies can be found. Note the scripts use the [DNN Cake Utils](https://github.com/DNNCommunity/Dnn.CakeUtils) assembly to do the heavy lifting.
+
+## Build to create packages
+
+This process uses Cake. Open Powershell at the root of the repository folder and enter:
 
-In order to build the whole solution and produce the install and upgrade packages, you simply need to open PowerShell and run the following command:
 ```
 .\build.ps1
 ```
 
-The version you are building is the current version on the branch you are. However there are 2 external repositories that get bundled into Dnn build:
-[Dnn.Connect CKEditor provider](https://github.com/DNN-Connect/CKEditorProvider) is the default HTML editor provider and its default branch is development.	
-[Dnn.ClientDependency](https://github.com/dnnsoftware/ClientDependency), the default branch is dnn
-Under normal situations they are the branches used for the next release, however if you have a need to specify a different branch to pull during the build you can specify them as such:
+This will trigger the build and packaging logic. The packages are created in the `artifacts` folder. 
+
+Note that (unless a build version has been specified, see below) this process will retrieve the latest version from Github and use that to version dlls and manifests. This creates a bunch of changed `.dnn` files and you'll need to make sure you don't include those in any Pull Requests when contributing.
+
+## Build to create/update your development site
+
+This process also uses Cake and follows the same logic as above, with the sole difference that the output is not a distribution zip file but rather this process pumps contents out to a directory you specify. Also you need to tell this process about your SQL server so that it can reset the database. When complete you should get the same experience as if you've built the platform and unpacked it on a server.
+
+### Prerequisites
+
+You'll need to be running IIS and SQL server (Express) locally for this to work. Create a folder on your hard disk and set it up in IIS as a web application. Then create or edit the local settings file.
+
+### Local Settings file
+
+The build process uses a local settings file which is excluded from source control so you won't accidentally upload this to Github. First open up Powershell at the root of this repository and run the following:
+
 ```
-.\build.ps1 -ScriptArgs '--CkBranch="branch-name"','--CdfBranch="branch-name"'
+.\Build.ps1 -Target CreateSettings
 ```
 
-If you encounter any build issues, please re-run the build with more verbosity as such:
+This will create a file called `settings.local.json` at the root with the following content:
+
+``` json
+{
+  "WebsitePath": "",
+  "WebsiteUrl": "",
+  "SaConnectionString": "server=(local);Trusted_Connection=True;",
+  "DnnConnectionString": "",
+  "DbOwner": "dbo",
+  "ObjectQualifier": "",
+  "DnnDatabaseName": "Dnn_Platform",
+  "DnnSqlUsername": "",
+  "DatabasePath": "",
+  "Version": "auto"
+}
 ```
-.\build.ps1 -Verbosity diagnostic
+
+The settings are as follows:
+
+|Name|Description|
+|---|---|
+|WebsitePath|Full physical path to the folder of your (dev) website|
+|WebsiteUrl|Url for that website (unused for now)|
+|SaConnectionString|SQL connection string with admin privileges. This allows the scripts to drop and recreate your database.|
+|DnnConnectionString|Connection string used in the web.config of your dev site to connect to the SQL database|
+|DbOwner|If you wish other than the default "dbo", please specify here.|
+|ObjectQualifier|The DNN database Object Qualifier. This is optional.|
+|DnnDatabaseName|Name to use for your DNN database. This is used in the drop and create scripts.|
+|DnnSqlUsername|User name for the account that has ownership of the database. This setting is used in the create scripts to ensure the account has the proper access rights.|
+|DatabasePath|Physical path to where you wish to create the database. Note this is just the folder, not the filename of the database.|
+|Version|You can force the build process to build for a specific version. E.g. 9.4.4.5. That will be used to build the correct versioned dlls and modules.|
+
+Once you've set up the above, run the following in Powershell:
+
+```
+.\Build.ps1 -Target ResetDevSite
 ```
-This will log much more information about the problem and allow you to open an issue with those more detailed logs.
 
-Also, the build scripts should leave you with 0 tracked modified files in git.
+This will attempt to delete all content in `WebsitePath` and will build DNN to that location.
+
+## Build Debug
+
+Note: **you need to have gone through the steps for setting up a dev site (see above) for this to work.**
+
+To build the .net projects to the right location, you'll need to create your override of the core build variables in the `DNN_Platform.local.build` file:
+
+``` xml
+<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <WebsitePath Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">C:\Path\to\my\DNN\DevSite</WebsitePath>
+  </PropertyGroup>
+</Project>
+```
+
+Once you've created this file every time you click "rebuild" in Visual Studio on a project (or the solution) you'll see the content change in your dev site.
+
+For the Webpack projects it is set up to read from the `settings.local.json` file and use the `WebsitePath` to copy generated js files to their right place.
+
+## Tips and tricks
+
+### Long paths
+
+To prevent issues with long paths in some build scripts, fork this repository in a short named folder on the root of any drive such as `c:\dnnsrc\` if you fork to a long path such as `c:\users\username\documents\dnn\source\` you may encounter long path issues.
+
+### Tracked files
+
+The build scripts should leave you with 0 tracked modified files in git.
 If a build fails midway and you have tracked artifacts, you can simply run:
 `git reset --hard` and/or `git clean -dxf` in order to come back to a clean state.
 
-If you encounter PowerShell security issues, please read [Cake - PowerShell Security](https://cakebuild.net/docs/tutorials/powershell-security)
+### Running Cake
+
+If you encounter PowerShell security issues, please read [Cake - PowerShell Security](https://cakebuild.net/docs/tutorials/powershell-security)
+
+### Git branching strategy
+
+Our default branch is called **develop**, this is the branch most pull requests should target in order to be merged into the very next release (bug fixes, minor improvements that are not breaking changes). If you know your change will be a breaking change or more risky, then you should submit it targeting the **future/xx** branch (where xx is the next major release). **release/x.x.x** branches are temporary, they get created at code-freeze to built an alpha release for the testing team, when initial testing is done, we publish one or more release candiate versions (RC1, RC2) as needed until we find the version stable for release, at which point we release that new version and close the release/x.x.x branch. The only pull requests that will be accepted for release/x.x.x branches are for regression issues (the problem was introduced in this very version) or showstopper issues (can't use Dnn with this bug in).

.github/ISSUE_TEMPLATE/bug-report.md

@@ -1,55 +1,56 @@
 ---
 name: Bug Report
-about: Create a report to help us improve
+about: Report a bug in DNN Platform
+labels: "Status: New"
+assignees: dnnsoftware/triage
 ---
-
 <!-- 
-  Please read contribution guideline first: https://github.com/dnnsoftware/Dnn.Platform/blob/development/CONTRIBUTING.md 
-  Any potential security issues should be sent to security@dnnsoftware.com, rather than posted on GitHub
--->
+  If you need community support or would like to solicit a Request for Comments (RFC), please post to the DNN Community forums at https://dnncommunity.org/forums for now.  In the future, we are planning to implement a more robust solution for cultivating new ideas and nuturing these from concept to creation.  We will update this template when this solution is generally available.  In the meantime, we appreciate your patience as we endeavor to streamline our GitHub focus and efforts.
+  
+  Please read the CONTRIBUTING guidelines at https://github.com/dnnsoftware/Dnn.Platform/blob/development/CONTRIBUTING.md prior to submitting an issue.
 
+  Any potential security issues SHOULD NOT be posted on GitHub.  Instead, please send an email to security@dnnsoftware.com.
+-->
 ## Description of bug
-Provide a clear and concise description of what the bug is.
+Provide a clear and concise description of the bug.
 
 ## Steps to reproduce
-List the steps to reproduce the behavior:
+List the precise steps to reproduce the bug:
 1. Go to '...'
 2. Click on '....'
-3. Scroll down to '....'
+3. Scroll to '....'
 4. See error
 
-## Current result
-Explain what the current result is.
+## Current behavior
+Explain the current behavior.
 
-## Expected result
-Provide a clear and concise description of what you expected to happen.
+## Expected behavior
+Provide a clear and concise description of the expected behavior.
 
 ## Screenshots
-If applicable, provide screenshots to help explain your problem.
+If applicable, provide screenshots to help explain the bug.
 
-## Error log
-Paste the error log that is related to this issue.
+## Error information
+Provide any error information (console errors, error logs, etc.) related to this bug.
 
 ## Additional context
-Add any other context about the bug that may be helpful for resolution.
+Provide any additional context that may be helpful in understanding and/or resolving the bug.
 
 ## Affected version
 <!-- 
 Please add X in at least one of the boxes as appropriate. In order for an issue to be accepted, a developer needs to be able to reproduce the issue on a currently supported version. If you are looking for a workaround for an issue with an older version, please visit the forums at https://dnncommunity.org/forums
 -->
-
 * [ ] 10.0.0 alpha build
-* [ ] 9.4.3 alpha build
-* [ ] 9.4.2 latest supported release
+* [ ] 9.5.0 alpha build
+* [ ] 9.4.4 latest supported release
 
 ## Affected browser
 <!-- 
-  Check all that apply and add more if necessary.
-  If possible, please also specify exact versions and mention the operating system
+  Check all that apply, and add more if necessary. As appropriate, please specify the exact version(s) of the browser and operating system.
 -->
-
 * [ ] Chrome
 * [ ] Firefox
 * [ ] Safari
-* [ ] Internet Explorer
-* [ ] Edge
+* [ ] Internet Explorer 11
+* [ ] Microsoft Edge (Classic)
+* [ ] Microsoft Edge Chromium

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: DNN Community Forums
+    url: https://dnncommunity.org/forums
+    about: Get help, solicit feedback and discuss new ideas regarding DNN Platform.
+  - name: DNN Documentation
+    url: https://dnndocs.com
+    about: Learn more about DNN Platform.

.github/ISSUE_TEMPLATE/enhancement-request.md

@@ -0,0 +1,37 @@
+---
+name: Enhancement Request
+about: Request an enhancement to DNN Platform
+labels: "Status: New"
+assignees: dnnsoftware/triage
+---
+<!-- 
+  If you need community support or would like to solicit a Request for Comments (RFC), please post to the DNN Community forums at https://dnncommunity.org/forums for now.  In the future, we are planning to implement a more robust solution for cultivating new ideas and nuturing these from concept to creation.  We will update this template when this solution is generally available.  In the meantime, we appreciate your patience as we endeavor to streamline our GitHub focus and efforts.
+  
+  Please read the CONTRIBUTING guidelines at https://github.com/dnnsoftware/Dnn.Platform/blob/development/CONTRIBUTING.md prior to submitting an issue.
+
+  Any potential security issues SHOULD NOT be posted on GitHub.  Instead, please send an email to security@dnnsoftware.com.
+-->
+## Description of problem
+Is your enhancement request related to a problem? Provide a clear and concise description of the problem.
+
+## Description of solution
+Provide a clear and concise description of the solution.
+
+## Description of alternatives considered
+Provide a clear and concise description of any alternative solutions considered.
+
+## Screenshots
+If applicable, provide screenshots to help explain the problem and/or enhancement.
+
+## Additional context
+Add any other context about the enhancement that may be helpful with implementation.
+
+## Affected browser
+<!-- 
+  Check all that apply, and add more if necessary. As appropriate, please specify the exact version(s) of the browser and operating system.
+-->
+* [ ] Chrome
+* [ ] Firefox
+* [ ] Safari
+* [ ] Internet Explorer
+* [ ] Edge