diff --git a/.github/BUILD.md b/.github/BUILD.md index a2406c58bd..9f755e1c05 100644 --- a/.github/BUILD.md +++ b/.github/BUILD.md @@ -1,14 +1,177 @@ -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. + +- 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? + +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. + +#### Table of contents + +[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) + +[Azure DevOps](#azure-devops) + +[Quirks](#quirks) + * [Powershell quirks](#powershell-quirks) + * [Git quirks](#git-quirks) + + +## Building from source + +Did you read ["Are you sure"](#are-you-sure)? + +### Quick! + +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: build/build.ps1 -## PowerShell Quirks +You might run into [Powershell quirks](#powershell-quirks). + +### 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 + +The object exposes the following properties: + +* `SolutionRoot`: the absolute path to the solution root +* `VisualStudio`: a Visual Studio object (see below) +* `NuGet`: the absolute path to the NuGet executable +* `Zip`: the absolute path to the 7Zip executable +* `VsWhere`: the absolute path to the VsWhere executable +* `NodePath`: the absolute path to the Node install +* `NpmPath`: the absolute path to the Npm install + +The Visual Studio object is `null` when Visual Studio has not been detected (eg on VSTS). When not null, the object exposes the following properties: + +* `Path`: Visual Studio installation path (eg some place under `Program Files`) +* `Major`: Visual Studio major version (eg `15` for VS 2017) +* `Minor`: Visual Studio minor version +* `MsBUild`: the absolute path to the MsBuild executable + +#### GetUmbracoVersion + +Gets an object representing the current Umbraco version. Example: + + $v = $ubuild.GetUmbracoVersion() + Write-Host $v.Semver + +The object exposes the following properties: + +* `Semver`: the semver object representing the version +* `Release`: the main part of the version (eg `7.6.33`) +* `Comment`: the pre release part of the version (eg `alpha02`) +* `Build`: the build number part of the version (eg `1234`) + +#### SetUmbracoVersion + +Modifies Umbraco files with the new version. + +>This entirely replaces the legacy `UmbracoVersion.txt` file. Do *not* edit version infos in files. + +The version must be a valid semver version. It can include a *pre release* part (eg `alpha02`) and/or a *build number* (eg `1234`). Examples: + + $ubuild.SetUmbracoVersion("7.6.33") + $ubuild.SetUmbracoVersion("7.6.33-alpha.2") + $ubuild.SetUmbracoVersion("7.6.33+1234") + $ubuild.SetUmbracoVersion("7.6.33-beta.5+5678") + +#### 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. + +**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 + +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 + +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 + +### 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. + +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. + + git clean -xdf . + +For git documentation see: +* git [clean]() +* 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 +* `compile-umbraco`: compiles Umbraco +* `pre-tests`: prepares the tests +* `compile-tests`: compiles the tests +* `pre-packages`: prepares the packages +* `pkg-zip`: creates the zip files +* `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 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. + +>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. + +## Quirks + +### PowerShell Quirks There is a good chance that running `build.ps1` ends up in error, with messages such as @@ -45,120 +208,6 @@ The best solution is to unblock the Zip file before un-zipping: right-click the PS> Get-ChildItem -Recurse *.* | Unblock-File -## Git Quirks +### Git Quirks -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 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 - -The object exposes the following properties: - -* `SolutionRoot`: the absolute path to the solution root -* `VisualStudio`: a Visual Studio object (see below) -* `NuGet`: the absolute path to the NuGet executable -* `Zip`: the absolute path to the 7Zip executable -* `VsWhere`: the absolute path to the VsWhere executable -* `NodePath`: the absolute path to the Node install -* `NpmPath`: the absolute path to the Npm install - -The Visual Studio object is `null` when Visual Studio has not been detected (eg on VSTS). When not null, the object exposes the following properties: - -* `Path`: Visual Studio installation path (eg some place under `Program Files`) -* `Major`: Visual Studio major version (eg `15` for VS 2017) -* `Minor`: Visual Studio minor version -* `MsBUild`: the absolute path to the MsBuild executable - -## GetUmbracoVersion - -Gets an object representing the current Umbraco version. Example: - - $v = $ubuild.GetUmbracoVersion() - Write-Host $v.Semver - -The object exposes the following properties: - -* `Semver`: the semver object representing the version -* `Release`: the main part of the version (eg `7.6.33`) -* `Comment`: the pre release part of the version (eg `alpha02`) -* `Build`: the build number part of the version (eg `1234`) - -## SetUmbracoVersion - -Modifies Umbraco files with the new version. - ->This entirely replaces the legacy `UmbracoVersion.txt` file. Do *not* edit version infos in files. - -The version must be a valid semver version. It can include a *pre release* part (eg `alpha02`) and/or a *build number* (eg `1234`). Examples: - - $ubuild.SetUmbracoVersion("7.6.33") - $ubuild.SetUmbracoVersion("7.6.33-alpha.2") - $ubuild.SetUmbracoVersion("7.6.33+1234") - $ubuild.SetUmbracoVersion("7.6.33-beta.5+5678") - -## 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 - -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 - -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 - -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 - -Continuous integration, nightly builds and release builds run on VSTS. - -VSTS 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 -* `compile-umbraco`: compiles Umbraco -* `pre-tests`: prepares the tests -* `compile-tests`: compiles the tests -* `pre-packages`: prepares the packages -* `pkg-zip`: creates the zip files -* `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. - -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 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. - -# Notes - -*This part needs to be cleaned up* - -Nightlies should use some sort of build number. - -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. - -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. - -/eof \ No newline at end of file +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). \ No newline at end of file diff --git a/.github/CLEAR.md b/.github/CLEAR.md deleted file mode 100644 index 84dc0b46d7..0000000000 --- a/.github/CLEAR.md +++ /dev/null @@ -1,34 +0,0 @@ -Umbraco Cms Clear --- ----- - -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. - -## Fast - -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 medias and views around, but in most cases, it will be enough. - -## More - -To perform a more complete clear, you will want to also delete the content of the media, views, masterpages, scripts... directories. - -## Full - -The following command will force remove all untracked files and directories, be they ignored by Git or not. Combined with `git reset` it can recreate a pristine working directory. - - git clean -xdf . - -## Docs - -See -* git [clean]() -* git [reset]() \ No newline at end of file diff --git a/.github/README.md b/.github/README.md index 9e7e977e9b..6d46466681 100644 --- 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 deleted file mode 100644 index 49a898cfe1..0000000000 --- a/.github/V8_GETTING_STARTED.md +++ /dev/null @@ -1,37 +0,0 @@ -## A quick start guide for getting up and runnning with Umbraco v8 - -### What you need: - -* [Visual Studio 2017 Community (Free)](https://www.visualstudio.com/vs/community/), or Professional, Enterprise, etc... _(**Minimum of Version 15.7** or higher, this is important, you WILL get issues with lesser versions)_ -* .NET Framework 4.7.2 installed, get it here: https://www.microsoft.com/net/download/thank-you/net472?survey=false -* .NET Framework 4.7.2 developer pack, get it here: https://www.microsoft.com/net/download/thank-you/net472-developer-pack _(be sure this is the ENU file which will be named `NDP472-DevPack-ENU.exe`)_ -* Clone the Umbraco repository using the `dev-v8` branch. If your git client doesn't support specifying the branch as you clone then use the command `git clone --single-branch -b dev-v8 `. _(If you clone the repo using the default v7 branch and then checkout the `dev-v8` branch you **might** get problems)_ - -### Start the solution - -* Open the `/src/umbraco.sln` Visual Studio solution -* Start the solution (easiest way is to use `ctrl + F5`) -* When the solution is first built this may take some time since it will restore all nuget and npm packages, build the .net solution and also build the angular solution -* When the website starts you'll see the Umbraco installer and just follow the prompts -* You're all set! - -### Want to run from a zip instead? - -If you just want to try out a few things, you can run the site from a zip file which you can download from here https://github.com/umbraco/Umbraco-CMS/releases/tag/temp8-cg18. - -We recommend running the site with the Visual Studio since you'll be able to remain up to date with the latest source code changes. - -### Making code changes - -* _[The process for making code changes in v8 is the same as v7](https://github.com/umbraco/Umbraco-CMS/blob/dev-v7/.github/CONTRIBUTING.md)_ -* Any .NET changes you make you just need to compile -* Any Angular/JS changes you make you will need to make sure you are running the Gulp build. Easiest way to do this is from within Visual Studio in the `Task Runner Explorer`. You can find this window by pressing `ctrl + q` and typing in `Task Runner Explorer`. In this window you'll see all Gulp tasks, double click on the `dev` task, this will compile the angular solution and start a file watcher, then any html/js changes you make are automatically built. -* When making js changes, you should have the chrome developer tools open to ensure that cache is disabled -* If you are only making C# changes and are not touching the UI code at all, you can significantly speed up the VS build by adding an empty file specifically called `~/src/preserve.belle`. The UI (Belle) build will then be skipped during a Rebuild. - -### What to work on? - -We are keeping track of [known issues and limitations here](http://issues.umbraco.org/issue/U4-11279). These line items will eventually be turned into actual tasks to be worked on. Feel free to help us keep this list updated if you find issues and even help fix some of these items. If there is a particular item you'd like to help fix please mention this on the task and we'll create a sub task for the item to continue discussion there. - -There's [a list of tasks for v8 that haven't been completed](https://github.com/umbraco/Umbraco-CMS/labels/release%2F8.0.0). If you are interested in helping out with any of these please mention this on the task. This list will be constantly updated as we begin to document and design some of the other tasks that still need to get done. -