Rework and update the contributing guide (#12165)
This commit is contained in:
Joe Glombek
119
.github/BUILD.md
vendored
119
.github/BUILD.md
vendored
@@ -4,30 +4,96 @@
|
||||
|
||||
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 about to [create a pull request for Umbraco][contribution guidelines]?
|
||||
- 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**
|
||||
## 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-UmbracoDocs](#build-umbracodocs)
|
||||
* [Verify-NuGet](#verify-nuget)
|
||||
* [Cleaning up](#cleaning-up)
|
||||
↖️ You can jump to any section by using the "table of contents" button (  ) above.
|
||||
|
||||
[Azure DevOps](#azure-devops)
|
||||
|
||||
[Quirks](#quirks)
|
||||
* [Powershell quirks](#powershell-quirks)
|
||||
* [Git quirks](#git-quirks)
|
||||
## Debugging source locally
|
||||
|
||||
Did you read ["Are you sure"](#are-you-sure)?
|
||||
|
||||
[More details about contributing to Umbraco and how to use the GitHub tooling can be found in our guide to contributing.][contribution guidelines]
|
||||
|
||||
If you want to run a build without debugging, see [Building from source](#building-from-source) below. This runs the build in the same way it is run on our build servers.
|
||||
|
||||
#### Debugging with VS Code
|
||||
|
||||
In order to build the Umbraco source code locally with Visual Studio Code, first make sure you have the following installed.
|
||||
|
||||
* [Visual Studio Code](https://code.visualstudio.com/)
|
||||
* [dotnet SDK v5.0](https://dotnet.microsoft.com/en-us/download)
|
||||
* [Node.js v10+](https://nodejs.org/en/download/)
|
||||
* npm v6.4.1+ (installed with Node.js)
|
||||
* [Git command line](https://git-scm.com/download/)
|
||||
|
||||
Open the root folder of the repository in Code.
|
||||
|
||||
To build the front end you'll need to open the command pallet (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>) and run `>Tasks: Run Task` followed by `Client Install` and then run the `Client Build` task in the same way.
|
||||
|
||||
You can also run the tasks manually on the command line:
|
||||
|
||||
```
|
||||
cd src\Umbraco.Web.UI.Client
|
||||
npm install
|
||||
npm run watch
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
cd src\Umbraco.Web.UI.Client
|
||||
npm install
|
||||
gulp watch
|
||||
```
|
||||
|
||||
**The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.**
|
||||
|
||||
You might run into [Gulp quirks](#gulp-quirks).
|
||||
|
||||
The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to [disable caching in the browser (check "Disable cache" on the "Network" tab of developer tools)][disable browser caching] to help you to see the changes you're making.
|
||||
|
||||
To run the C# portion of the project, either hit <kbd>F5</kbd> to begin debugging, or manually using the command line:
|
||||
|
||||
```
|
||||
dotnet watch --project .\src\Umbraco.Web.UI\Umbraco.Web.UI.csproj
|
||||
```
|
||||
|
||||
**The initial C# build might take a _really_ long time (seriously, go and make a cup of coffee!) - but don't worry, this will be faster on subsequent runs.**
|
||||
|
||||
When the page eventually loads in your web browser, you can follow the installer to set up a database for debugging. You may also wish to install a [starter kit][starter kits] to ease your debugging.
|
||||
|
||||
#### Debugging with Visual Studio
|
||||
|
||||
In order to build the Umbraco source code locally with Visual Studio, first make sure you have the following installed.
|
||||
|
||||
* [Visual Studio 2019 v16.8+ with .NET 5+](https://visualstudio.microsoft.com/vs/) ([the community edition is free](https://www.visualstudio.com/thank-you-downloading-visual-studio/?sku=Community&rel=15) for you to use to contribute to Open Source projects)
|
||||
* [Node.js v10+](https://nodejs.org/en/download/)
|
||||
* npm v6.4.1+ (installed with Node.js)
|
||||
* [Git command line](https://git-scm.com/download/)
|
||||
|
||||
The easiest way to get started is to open `umbraco.sln` in Visual Studio.
|
||||
|
||||
To build the front end, you'll first need to run `cd src\Umbraco.Web.UI.Client && npm install` in the command line (or `cd src\Umbraco.Web.UI.Client; npm install` in PowerShell). Then find the Task Runner Explorer (View → Other Windows → Task Runner Explorer) and run the `build` task under `Gulpfile.js`. You may need to refresh the Task Runner Explorer before the tasks load.
|
||||
|
||||
If you're working on the backoffice, you may wish to run the `dev` command instead while you're working with it, so changes are copied over to the appropriate directories and you can refresh your browser to view the results of your changes.
|
||||
|
||||
**The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.**
|
||||
|
||||
You might run into [Gulp quirks](#gulp-quirks).
|
||||
|
||||
The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to [disable caching in the browser (check "Disable cache" on the "Network" tab of developer tools)][disable browser caching] to help you to see the changes you're making.
|
||||
|
||||
"The rest" is a C# based codebase, which is mostly ASP.NET Core MVC based. You can make changes, build them in Visual Studio, and hit <kbd>F5</kbd> to see the result.
|
||||
|
||||
**The initial C# build might take a _really_ long time (seriously, go and make a cup of coffee!) - but don't worry, this will be faster on subsequent runs.**
|
||||
|
||||
When the page eventually loads in your web browser, you can follow the installer to set up a database for debugging. You may also wish to install a [starter kit][starter kits] to ease your debugging.
|
||||
|
||||
## Building from source
|
||||
|
||||
@@ -38,13 +104,14 @@ Did you read ["Are you sure"](#are-you-sure)?
|
||||
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
|
||||
|
||||
|
||||
If you only see a build.bat-file, you're probably on the wrong branch. If you switch to the correct branch (v8/contrib) the file will appear and you can build it.
|
||||
|
||||
You might run into [Powershell quirks](#powershell-quirks).
|
||||
|
||||
If it runs without errors; Hooray! Now you can continue with [the next step](CONTRIBUTING.md#how-do-i-begin) and open the solution and build it.
|
||||
|
||||
|
||||
### Build Infrastructure
|
||||
|
||||
The Umbraco Build infrastructure relies on a PowerShell object. The object can be retrieved with:
|
||||
@@ -145,7 +212,7 @@ To perform a more complete clear, you will want to also delete the content of th
|
||||
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](<https://git-scm.com/docs/git-clean>)
|
||||
* git [reset](<https://git-scm.com/docs/git-reset>)
|
||||
@@ -214,3 +281,19 @@ The best solution is to unblock the Zip file before un-zipping: right-click the
|
||||
### 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).
|
||||
|
||||
### Gulp Quirks
|
||||
|
||||
You may need to run the following commands to set up gulp properly:
|
||||
|
||||
```
|
||||
npm cache clean --force
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
|
||||
|
||||
|
||||
[ contribution guidelines]: CONTRIBUTING.md "Read the guide to contributing for more details on contributing to Umbraco"
|
||||
[ starter kits ]: https://our.umbraco.com/packages/?category=Starter%20Kits&version=9 "Browse starter kits available for v9 on Our "
|
||||
[ disable browser caching ]: https://techwiser.com/disable-cache-google-chrome-firefox "Instructions on how to disable browser caching in Chrome and Firefox"
|
||||
|
||||
Reference in New Issue
Block a user