Skip to content

Commit 953e6f2

Browse files
glombekglombek
authored
Rework and update the contributing guide (#12165)
1 parent ebb1dc2 commit 953e6f2

5 files changed

+250
-202
lines changed

‎.github/BUILD.md

+101-18
Original file line numberDiff line numberDiff line change
@@ -4,30 +4,96 @@
44

55
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.
66

7-
- Are you about to create a pull request for Umbraco?
7+
- Are you about to [create a pull request for Umbraco][contribution guidelines]?
88
- Are you trying to get to the bottom of a problem in your existing Umbraco installation?
99

1010
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.
1111

12-
**Table of contents**
12+
## Table of contents
1313

14-
[Building from source](#building-from-source)
15-
* [The quick build](#quick)
16-
* [Build infrastructure](#build-infrastructure)
17-
* [Properties](#properties)
18-
* [GetUmbracoVersion](#getumbracoversion)
19-
* [SetUmbracoVersion](#setumbracoversion)
20-
* [Build](#build)
21-
* [Build-UmbracoDocs](#build-umbracodocs)
22-
* [Verify-NuGet](#verify-nuget)
23-
* [Cleaning up](#cleaning-up)
14+
↖️ You can jump to any section by using the "table of contents" button ( ![Table of contents icon](img/tableofcontentsicon.svg) ) above.
2415

25-
[Azure DevOps](#azure-devops)
2616

27-
[Quirks](#quirks)
28-
* [Powershell quirks](#powershell-quirks)
29-
* [Git quirks](#git-quirks)
17+
## Debugging source locally
3018

19+
Did you read ["Are you sure"](#are-you-sure)?
20+
21+
[More details about contributing to Umbraco and how to use the GitHub tooling can be found in our guide to contributing.][contribution guidelines]
22+
23+
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.
24+
25+
#### Debugging with VS Code
26+
27+
In order to build the Umbraco source code locally with Visual Studio Code, first make sure you have the following installed.
28+
29+
* [Visual Studio Code](https://code.visualstudio.com/)
30+
* [dotnet SDK v5.0](https://dotnet.microsoft.com/en-us/download)
31+
* [Node.js v10+](https://nodejs.org/en/download/)
32+
* npm v6.4.1+ (installed with Node.js)
33+
* [Git command line](https://git-scm.com/download/)
34+
35+
Open the root folder of the repository in Code.
36+
37+
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.
38+
39+
You can also run the tasks manually on the command line:
40+
41+
```
42+
cd src\Umbraco.Web.UI.Client
43+
npm install
44+
npm run watch
45+
```
46+
47+
or
48+
49+
```
50+
cd src\Umbraco.Web.UI.Client
51+
npm install
52+
gulp watch
53+
```
54+
55+
**The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.**
56+
57+
You might run into [Gulp quirks](#gulp-quirks).
58+
59+
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.
60+
61+
To run the C# portion of the project, either hit <kbd>F5</kbd> to begin debugging, or manually using the command line:
62+
63+
```
64+
dotnet watch --project .\src\Umbraco.Web.UI\Umbraco.Web.UI.csproj
65+
```
66+
67+
**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.**
68+
69+
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.
70+
71+
#### Debugging with Visual Studio
72+
73+
In order to build the Umbraco source code locally with Visual Studio, first make sure you have the following installed.
74+
75+
* [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)
76+
* [Node.js v10+](https://nodejs.org/en/download/)
77+
* npm v6.4.1+ (installed with Node.js)
78+
* [Git command line](https://git-scm.com/download/)
79+
80+
The easiest way to get started is to open `umbraco.sln` in Visual Studio.
81+
82+
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.
83+
84+
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.
85+
86+
**The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.**
87+
88+
You might run into [Gulp quirks](#gulp-quirks).
89+
90+
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.
91+
92+
"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.
93+
94+
**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.**
95+
96+
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.
3197

3298
## Building from source
3399

@@ -38,13 +104,14 @@ Did you read ["Are you sure"](#are-you-sure)?
38104
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:
39105

40106
build/build.ps1
41-
107+
42108
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.
43109

44110
You might run into [Powershell quirks](#powershell-quirks).
45111

46112
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.
47113

114+
48115
### Build Infrastructure
49116

50117
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
145212
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.
146213

147214
git clean -xdf .
148-
215+
149216
For git documentation see:
150217
* git [clean](<https://git-scm.com/docs/git-clean>)
151218
* 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
214281
### Git Quirks
215282

216283
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).
284+
285+
### Gulp Quirks
286+
287+
You may need to run the following commands to set up gulp properly:
288+
289+
```
290+
npm cache clean --force
291+
npm ci
292+
npm run build
293+
```
294+
295+
296+
297+
[ contribution guidelines]: CONTRIBUTING.md "Read the guide to contributing for more details on contributing to Umbraco"
298+
[ starter kits ]: https://our.umbraco.com/packages/?category=Starter%20Kits&version=9 "Browse starter kits available for v9 on Our "
299+
[ disable browser caching ]: https://techwiser.com/disable-cache-google-chrome-firefox "Instructions on how to disable browser caching in Chrome and Firefox"

0 commit comments

Comments
 (0)