You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/BUILD.md
+70-35Lines changed: 70 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,81 +13,117 @@ If the answer is yes, please read on. Otherwise, make sure to head on over [to t
13
13
14
14
↖️ You can jump to any section by using the "table of contents" button (  ) above.
15
15
16
-
## Debugging source locally
16
+
## Working with the Umbraco source code
17
17
18
18
Did you read ["Are you sure"](#are-you-sure)?
19
19
20
20
[More details about contributing to Umbraco and how to use the GitHub tooling can be found in our guide to contributing.][contribution guidelines]
21
21
22
22
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.
23
23
24
-
> [!NOTE]
25
-
> 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.
24
+
If you've got this far and are keen to get stuck in helping us fix a bug or implement a feature, great! Please read on...
26
25
27
-
#### Debugging with VS Code
26
+
###Prerequisites
28
27
29
-
In order to build the Umbraco source code locally with Visual Studio Code, first make sure you have the following installed.
28
+
In order to work with the Umbraco source code locally, first make sure you have the following installed.
30
29
31
-
-[Visual Studio Code](https://code.visualstudio.com/)
30
+
-Your favourite IDE: [Visual Studio 2022 v17+ with .NET 7+](https://visualstudio.microsoft.com/vs/), [Rider](https://www.jetbrains.com/rider/) or [Visual Studio Code](https://code.visualstudio.com/)
Open the root folder of the repository in Visual Studio Code.
36
+
### Familiarizing yourself with the code
37
+
38
+
Umbraco is a .NET application using C#. The solution is broken down into multiple projects. There are several class libraries. The `Umbraco.Web.UI` project is the main project that hosts the back office and login screen. This is the project you will want to run to see your changes.
39
+
40
+
There are two web projects in the solution with client-side assets based on TypeScript, `Umbraco.Web.UI.Client` and `Umbraco.Web.UI.Login`.
38
41
39
-
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 Build`.
42
+
There are a few different ways to work locally when implementing features or fixing issues with the Umbraco CMS. Depending on whether you are working solely on the front-end, solely on the back-end, or somewhere in between, you may find different workflows work best for you.
40
43
41
-
You can also run the tasks manually on the command line:
44
+
Here are some suggestions based on how we work on developing Umbraco at HQ.
45
+
46
+
### First checkout
47
+
48
+
When you first clone the source code, build the whole solution via your IDE. You can then start the `Umbraco.Web.UI` project via the IDE or the command line and should find everything across front and back-end is built and running.
42
49
43
50
```
44
-
cd src\Umbraco.Web.UI.Client
45
-
npm i
46
-
npm run build:for:cms
51
+
cd <solution root>\src\Umbraco.Web.UI
52
+
dotnet run --no-build
47
53
```
48
54
49
-
If you want to make changes to the UI, you can choose to run a front-end development server. To learn more please read the Umbraco.Web.UI.Client README.md [Run against a local Umbraco instance](../src/Umbraco.Web.UI.Client/.github/README.md#run-against-a-local-umbraco-instance) for more information.
55
+
When the page loads in your web browser, you can follow the installer to set up a database for debugging. When complete, you will have an empty Umbraco installation to begin working with. You may also wish to install a [starter kit][https://marketplace.umbraco.com/category/themes-&-starter-kits] to ease your debugging.
56
+
57
+
### Back-end only changes
58
+
59
+
If you are working on back-end only features, when switching branches or pulling down the latest from GitHub, you will find the front-end getting rebuilt periodically when you look to build the back-end changes. This can take a while and slow you down. So if for a period of time you don't care about changes in the front-end, you can disable this build step.
50
60
51
-
The login screen is a different frontend build, for that one you can run it as follows:
61
+
Go to `Umbraco.Cms.StaticAssets.csproj` and comment out the following lines of MsBuild by adding a REM statement in front:
52
62
53
63
```
54
-
cd src\Umbraco.Web.UI.Login
55
-
npm i
56
-
npm run dev
64
+
REM npm ci --no-fund --no-audit --prefer-offline
65
+
REM npm run build:for:cms
57
66
```
58
67
59
-
If you just want to build the Login screen to `Umbraco.Web.UI` then instead of running `dev`, you can do: `npm run build`.
68
+
Just be careful not to include this change in your PR.
60
69
61
-
To run the C# portion of the project, either hit <kbd>F5</kbd> to begin debugging, or manually using the command line:
70
+
### Front-end only changes
71
+
72
+
Conversely, if you are working on front-end only, you want to build the back-end once and then run it. Before you do so, update the configuration in `appSettings.json` to add the following under `Umbraco:Cms:Security`:
**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.**
81
+
Then run Umbraco from the command line.
68
82
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.
83
+
```
84
+
cd <solution root>\src\Umbraco.Web.UI
85
+
dotnet run --no-build
86
+
```
70
87
71
-
#### Debugging with Visual Studio
88
+
In another terminal window, run the following to watch the front-end changes and launch Umbraco using the URL indicated from this task.
72
89
73
-
In order to build the Umbraco source code locally with Visual Studio, first make sure you have the following installed.
90
+
```
91
+
cd <solution root>\src\Umbraco.Web.UI.Client
92
+
npm run dev:server
93
+
```
74
94
75
-
-[Visual Studio 2022 v17+ with .NET 7+](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)
You'll find as you make changes to the front-end files, the updates will be picked up and your browser refreshed automatically.
96
+
97
+
> [!NOTE]
98
+
> 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.
99
+
100
+
Whilst most of the backoffice code lives in `Umbraco.Web.UI.Client`, the login screen is in a separate project. If you do any work with that you can build with:
101
+
102
+
```
103
+
cd <solution root>\src\Umbraco.Web.UI.Login
104
+
npm run build
105
+
```
106
+
107
+
In both front-end projects, if you've refreshed your branch from the latest on GitHub you may need to update front-end dependencies.
79
108
80
-
The easiest way to get started is to open `umbraco.sln` in Visual Studio.
109
+
To do that, run:
81
110
82
-
Umbraco 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. There are two web projects in the solution, `Umbraco.Web.UI.Client` and `Umbraco.Web.UI.Login`. They each have their own build process and can be run separately. The `Umbraco.Web.UI` project is the main project that hosts the back office and login screen. This is the project you will want to run to see your changes. It will automatically restore and build the client projects when you run it.
111
+
```
112
+
npm ci --no-fund --no-audit --prefer-offline
113
+
```
83
114
84
-
If you want to watch the UI Client to `Umbraco.Web.UI` then you can open a terminal in `src/Umbraco.Web.UI.Client` where you can run `npm run dev:mock` manually. This will launch the Vite dev server on http://localhost:5173 and watch for changes with mocked API responses.
115
+
### Full-stack changes
85
116
86
-
You can also run `npm run dev:server` to run the Vite server against a local Umbraco instance. In this case, you need to have the .NET project running and accept connections from the Vite server. Please see the Umbraco.Web.UI.Client README.md [Run against a local Umbraco instance](../src/Umbraco.Web.UI.Client/.github/README.md#run-against-a-local-umbraco-instance) for more information.
117
+
If working across both front and back-end, follow both methods and use `dotnet watch`, or re-run `dotnet run` (or `dotnet build` followed by `dotnet run --no-build`) whenever you need to update the back-end code.
87
118
88
-
**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.**
119
+
Request and response models used by the management APIs are made available client-side as generated code. If you make changes to the management API, you can re-generate the typed client code with:
120
+
121
+
```
122
+
cd <solution root>\src\Umbraco.Web.UI.Client
123
+
npm run generate:server-api-dev
124
+
```
89
125
90
-
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.
126
+
Please also update the `OpenApi.json` file held in the solution by copying and pasting the output from `/umbraco/swagger/management/swagger.json`.
91
127
92
128
## Building from source
93
129
@@ -148,5 +184,4 @@ The produced artifacts are published in a container that can be downloaded from
148
184
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).
149
185
150
186
[ contribution guidelines]: CONTRIBUTING.md"Read the guide to contributing for more details on contributing to Umbraco"
151
-
[ starter kits ]: https://our.umbraco.com/packages/?category=Starter%20Kits&version=9"Browse starter kits available for v9 on Our "
152
187
[ disable browser caching ]: https://techwiser.com/disable-cache-google-chrome-firefox"Instructions on how to disable browser caching in Chrome and Firefox"
Copy file name to clipboardExpand all lines: .github/CONTRIBUTING.md
+10-6Lines changed: 10 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,15 +12,15 @@ The following steps are a quick-start guide:
12
12
1.**Fork**
13
13
14
14
Create a fork of [`Umbraco-CMS` on GitHub](https://github.com/umbraco/Umbraco-CMS)
15
-
15
+
16
16
17
-
17
+
18
18
2.**Clone**
19
19
20
20
When GitHub has created your fork, you can clone it in your favorite Git tool or on the command line with `git clone https://github.com/[YourUsername]/Umbraco-CMS`.
21
-
22
-
23
-
21
+
22
+
23
+
24
24
3.**Switch to the correct branch**
25
25
26
26
Switch to the `contrib` branch
@@ -31,7 +31,11 @@ The following steps are a quick-start guide:
31
31
32
32
5.**Branch**
33
33
34
-
Create a new branch now and name it after the issue you're fixing, we usually follow the format: `temp/12345`. This means it's a temporary branch for the particular issue you're working on, in this case issue number `12345`. Don't commit to `contrib`, create a new branch first.
34
+
Create a new branch now and name it after the issue you're fixing, we usually follow the format: `v{major}/{feature|bugfix|task}/{issue}-{description}`. For example: `v15/bugfix/18132-rte-tinymce-onchange-value-check`.
35
+
36
+
This means it's a temporary branch for the particular issue you're working on, in this case a bug fix for issue number `18132` that affects Umbraco 15.
37
+
38
+
Don't commit to `contrib`, create a new branch first.
0 commit comments