More readme updates

Nuklon · Mar 19, 2019 · 23656f0 · 23656f0
1 parent 685c4e3
commit 23656f0
Show file tree

Hide file tree

Showing 4 changed files with 106 additions and 128 deletions.
diff --git a/.github/BUILD.md b/.github/BUILD.md
@@ -1,63 +1,56 @@
-Umbraco Cms Build
---
-----
+# Umbraco Cms Build
 
-# Quick!
+## Are you sure?
 
-To build Umbraco, fire PowerShell and move to Umbraco's repository root (the directory that contains `src`, `build`, `README.md`...). There, trigger the build with the following command:
+In order to use Umbraco as a CMS and build your website with it, you should not build it yourself. If you're reading this then you're trying to contribute to Umbraco or you're debugging a complex issue.
 
-    build/build.ps1
-
-## PowerShell Quirks
+- Are you about to create a pull request for Umbraco?
+- Are you trying to get to the bottom of a problem in your existing Umbraco installation?
 
-There is a good chance that running `build.ps1` ends up in error, with messages such as
+If the answer is yes, please read on. Otherwise, make sure to head on over [to the download page](https://our.umbraco.com/download) and start using Umbraco CMS as intended.
 
->The file ...\build.ps1 is not digitally signed. You cannot run this script on the current system. For more information about running scripts and setting execution policy, see about_Execution_Policies.
+#### Table of contents
 
-PowerShell has *Execution Policies* that may prevent the script from running. You can check the current policies with:
+[Building from source](#building-from-source)
+  * [The quick build](#quick!)
+  * [Build infrastructure](#build-infrastructure)
+    * [Properties](#properties)
+    * [GetUmbracoVersion](#getumbracoversion)
+    * [SetUmbracoVersion](#setumbracoversion)
+    * [Build](#build)
+    * [Build](#build)
+    * [Build-UmbracoDocs](#build-umbracodocs)
+    * [Verify-NuGet](#verify-nuget)
+  * [Cleaning up](#cleaning-up)
 
-    PS> Get-ExecutionPolicy -List
-
-            Scope ExecutionPolicy
-            ----- ---------------
-    MachinePolicy       Undefined
-       UserPolicy       Undefined
-          Process       Undefined
-      CurrentUser       Undefined
-     LocalMachine    RemoteSigned
+[Azure DevOps](#azure-devops)
 
-Policies can be `Restricted`, `AllSigned`, `RemoteSigned`, `Unrestricted` and `Bypass`. Scopes can be `MachinePolicy`, `UserPolicy`, `Process`, `CurrentUser`, `LocalMachine`. You need the current policy to be `RemoteSigned`&mdash;as long as it is `Undefined`, the script cannot run. You can change the current user policy with:
+[Quirks](#quirks)
+  * [Powershell quirks](#powershell-quirks)
+  * [Git quirks](#git-quirks)
 
-    PS> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
 
-Alternatively, you can do it at machine level, from within an elevated PowerShell session:
+## Building from source
 
-    PS> Set-ExecutionPolicy -Scope LocalMachine -ExecutionPolicy RemoteSigned
+Did you read ["Are you sure"](#are-you-sure)?
 
-And *then* the script should run. It *might* however still complain about executing scripts, with messages such as:
+### Quick!
 
->Security warning - Run only scripts that you trust. While scripts from the internet can be useful, this script can potentially harm your computer. If you trust this script, use the Unblock-File cmdlet to allow the script to run without this warning message. Do you want to run ...\build.ps1?
-[D] Do not run  [R] Run once  [S] Suspend  [?] Help (default is "D"):
-
-This is usually caused by the scripts being *blocked*. And that usually happens when the source code has been downloaded as a Zip file. When Windows downloads Zip files, they are marked as *blocked* (technically, they have a Zone.Identifier alternate data stream, with a value of "3" to indicate that they were downloaded from the Internet). And when such a Zip file is un-zipped, each and every single file is also marked as blocked.
-
-The best solution is to unblock the Zip file before un-zipping: right-click the files, open *Properties*, and there should be a *Unblock* checkbox at the bottom of the dialog. If, however, the Zip file has already been un-zipped, it is possible to recursively unblock all files from PowerShell with:
-
-    PS> Get-ChildItem -Recurse *.* | Unblock-File
-
-## Git Quirks
+To build Umbraco, fire up PowerShell and move to Umbraco's repository root (the directory that contains `src`, `build`, `LICENSE.md`...). There, trigger the build with the following command:
 
-Git might have issues dealing with long file paths during build. You may want/need to enable `core.longpaths` support (see [this page](https://github.com/msysgit/msysgit/wiki/Git-cannot-create-a-file-or-directory-with-a-long-path) for details).
+    build/build.ps1
+
+You might run into [Powershell quirks](#powershell-quirks).
 
-# Build Infrastructure
+### Build Infrastructure
 
 The Umbraco Build infrastructure relies on a PowerShell object. The object can be retrieved with:
 
     $ubuild = build/build.ps1 -get
 
 The object exposes various properties and methods that can be used to fine-grain build Umbraco. Some, but not all, of them are detailed below.
 
-## Properties
+#### Properties
 
 The object exposes the following properties:
 
@@ -76,7 +69,7 @@ The Visual Studio object is `null` when Visual Studio has not been detected (eg
 * `Minor`: Visual Studio minor version
 * `MsBUild`: the absolute path to the MsBuild executable
 
-## GetUmbracoVersion
+#### GetUmbracoVersion
 
 Gets an object representing the current Umbraco version. Example:
 
@@ -90,7 +83,7 @@ The object exposes the following properties:
 * `Comment`: the pre release part of the version (eg `alpha02`)
 * `Build`: the build number part of the version (eg `1234`)
 
-## SetUmbracoVersion
+#### SetUmbracoVersion
 
 Modifies Umbraco files with the new version.
 
@@ -103,37 +96,62 @@ The version must be a valid semver version. It can include a *pre release* part
     $ubuild.SetUmbracoVersion("7.6.33+1234")
     $ubuild.SetUmbracoVersion("7.6.33-beta.5+5678")
 
-## Build
+#### Build
 
 Builds Umbraco. Temporary files are generated in `build.tmp` while the actual artifacts (zip files, NuGet packages...) are produced in `build.out`. Example:
 
     $ubuild.Build()
 
 Some log files, such as MsBuild logs, are produced in `build.tmp` too. The `build` directory should remain clean during a build.
 
-### web.config
+**Note: web.config**
 
 Building Umbraco requires a clean `web.config` file in the `Umbraco.Web.UI` project. If a `web.config` file already exists, the `pre-build` task (see below) will save it as `web.config.temp-build` and replace it with a clean copy of `web.Template.config`. The original file is replaced once it is safe to do so, by the `pre-packages` task.
 
-## Build-UmbracoDocs
+#### Build-UmbracoDocs
 
 Builds umbraco documentation. Temporary files are generated in `build.tmp` while the actual artifacts (docs...) are produced in `build.out`. Example:
 
     Build-UmbracoDocs
 
 Some log files, such as MsBuild logs, are produced in `build.tmp` too. The `build` directory should remain clean during a build.
 
-## Verify-NuGet
+#### Verify-NuGet
 
 Verifies that projects all require the same version of their dependencies, and that NuSpec files require versions that are consistent with projects. Example:
 
     Verify-NuGet
 
-# VSTS
+### Cleaning up
+
+Once the solution has been used to run a site, one may want to "reset" the solution in order to run a fresh new site again.
+
+At the very minimum, you want
+
+    git clean -Xdf src/Umbraco.Web.UI/App_Data
+    rm src/Umbraco.Web.UI/web.config
+
+Then, a simple 'Rebuild All' in Visual Studio will recreate a fresh `web.config` but should be quite fast (since it does not really need to rebuild anything).
+
+The `clean` Git command force (`-f`) removes (`-X`, note the capital X) all files and directories (`-d`) that are ignored by Git.
+
+This will leave media files and views around, but in most cases, it will be enough.
+
+To perform a more complete clear, you will want to also delete the content of the media, views, scripts... directories.
 
-Continuous integration, nightly builds and release builds run on VSTS.
+The following command will force remove all untracked files and directories, whether they are ignored by Git or not. Combined with `git reset` it can recreate a pristine working directory. 
 
-VSTS uses the `Build-Umbraco` command several times, each time passing a different *target* parameter. The supported targets are:
+    git clean -xdf .
+
+For git documentation see:
+* git [clean](<https://git-scm.com/docs/git-clean>)
+* git [reset](<https://git-scm.com/docs/git-reset>)
+
+## Azure DevOps
+
+Umbraco uses Azure DevOps for continuous integration, nightly builds and release builds. The Umbraco CMS project on DevOps [is available for anonymous users](https://umbraco.visualstudio.com/Umbraco%20Cms).
+
+DevOps uses the `Build-Umbraco` command several times, each time passing a different *target* parameter. The supported targets are:
 
 * `pre-build`: prepares the build
 * `compile-belle`: compiles Belle
@@ -145,20 +163,51 @@ VSTS uses the `Build-Umbraco` command several times, each time passing a differe
 * `pre-nuget`: prepares NuGet packages
 * `pkg-nuget`: creates NuGet packages
 
-All these targets are executed when `Build-Umbraco` is invoked without a parameter (or with the `all` parameter). On VSTS, compilations (of Umbraco and tests) are performed by dedicated VSTS tasks. Similarly, creating the NuGet packages is also performed by dedicated VSTS tasks.
+All these targets are executed when `Build-Umbraco` is invoked without a parameter (or with the `all` parameter). On VSTS, compilations (of Umbraco and tests) are performed by dedicated DevOps tasks. Similarly, creating the NuGet packages is also performed by dedicated DevOps tasks.
+
+Finally, the produced artifacts are published in two containers that can be downloaded from DevOps: `zips` contains the zip files while `nuget` contains the NuGet packages.
 
-Finally, the produced artifacts are published in two containers that can be downloaded from VSTS: `zips` contains the zip files while `nuget` contains the NuGet packages.
+>During a DevOps build, some environment `UMBRACO_*` variables are exported by the `pre-build` target and can be reused in other targets *and* in DevOps tasks. The `UMBRACO_TMP` environment variable is used in `Umbraco.Tests` to disable some tests that have issues with DevOps at the moment.
 
->During a VSTS build, some environment `UMBRACO_*` variables are exported by the `pre-build` target and can be reused in other targets *and* in VSTS tasks. The `UMBRACO_TMP` environment variable is used in `Umbraco.Tests` to disable some tests that have issues with VSTS at the moment.
+## Quirks
 
-# Notes
+### PowerShell Quirks
 
-*This part needs to be cleaned up*
+There is a good chance that running `build.ps1` ends up in error, with messages such as
+
+>The file ...\build.ps1 is not digitally signed. You cannot run this script on the current system. For more information about running scripts and setting execution policy, see about_Execution_Policies.
+
+PowerShell has *Execution Policies* that may prevent the script from running. You can check the current policies with:
 
-Nightlies should use some sort of build number.
+    PS> Get-ExecutionPolicy -List
+
+            Scope ExecutionPolicy
+            ----- ---------------
+    MachinePolicy       Undefined
+       UserPolicy       Undefined
+          Process       Undefined
+      CurrentUser       Undefined
+     LocalMachine    RemoteSigned
 
-We should increment versions as soon as a version is released. Ie, as soon as `7.6.33` is released, we should `Set-UmbracoVersion 7.6.34-alpha` and push.
+Policies can be `Restricted`, `AllSigned`, `RemoteSigned`, `Unrestricted` and `Bypass`. Scopes can be `MachinePolicy`, `UserPolicy`, `Process`, `CurrentUser`, `LocalMachine`. You need the current policy to be `RemoteSigned`&mdash;as long as it is `Undefined`, the script cannot run. You can change the current user policy with:
+
+    PS> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+
+Alternatively, you can do it at machine level, from within an elevated PowerShell session:
+
+    PS> Set-ExecutionPolicy -Scope LocalMachine -ExecutionPolicy RemoteSigned
+
+And *then* the script should run. It *might* however still complain about executing scripts, with messages such as:
+
+>Security warning - Run only scripts that you trust. While scripts from the internet can be useful, this script can potentially harm your computer. If you trust this script, use the Unblock-File cmdlet to allow the script to run without this warning message. Do you want to run ...\build.ps1?
+[D] Do not run  [R] Run once  [S] Suspend  [?] Help (default is "D"):
+
+This is usually caused by the scripts being *blocked*. And that usually happens when the source code has been downloaded as a Zip file. When Windows downloads Zip files, they are marked as *blocked* (technically, they have a Zone.Identifier alternate data stream, with a value of "3" to indicate that they were downloaded from the Internet). And when such a Zip file is un-zipped, each and every single file is also marked as blocked.
+
+The best solution is to unblock the Zip file before un-zipping: right-click the files, open *Properties*, and there should be a *Unblock* checkbox at the bottom of the dialog. If, however, the Zip file has already been un-zipped, it is possible to recursively unblock all files from PowerShell with:
+
+    PS> Get-ChildItem -Recurse *.* | Unblock-File
 
-NuGet / NuSpec consistency checks are performed in tests. We should move it so it is done as part of the PowerShell script even before we try to compile and run the tests.
+### Git Quirks
 
-/eof
+Git might have issues dealing with long file paths during build. You may want/need to enable `core.longpaths` support (see [this page](https://github.com/msysgit/msysgit/wiki/Git-cannot-create-a-file-or-directory-with-a-long-path) for details).
diff --git a/.github/CLEAR.md b/.github/CLEAR.md
diff --git a/.github/README.md b/.github/README.md
@@ -12,8 +12,8 @@ See the official [Umbraco website](https://umbraco.com) for an introduction, cor
 
 - [Getting Started](#getting-started)
 - [Documentation](#documentation)
-- [Contributing](#contributing)
 - [Community](#join-the-umbraco-community)
+- [Contributing](#contributing)
 
 Please also see our [Code of Conduct](CODE_OF_CONDUCT.md).
 

diff --git a/.github/V8_GETTING_STARTED.md b/.github/V8_GETTING_STARTED.md