Merge branch 'contrib' into span-split

Author: Henr1k80

.github/BUILD.md

@@ -1,5 +1,7 @@
 # Umbraco CMS Build
 
+This guide will explain how you can build the Umbraco CMS from the source code. You will most likely want to do this if your are setting up a local development environment for contributing code updates to the project. You will need this in order to develop and test your fix or feature.
+
 ## Are you sure?
 
 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.
@@ -13,81 +15,117 @@ If the answer is yes, please read on. Otherwise, make sure to head on over [to t
 
 ↖️ You can jump to any section by using the "table of contents" button ( ![Table of contents icon](img/tableofcontentsicon.svg) ) above.
 
-## Debugging source locally
+## Working with the Umbraco source code
 
 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.
 
-> [!NOTE]
-> 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.
+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...
 
-#### Debugging with VS Code
+### Prerequisites
 
-In order to build the Umbraco source code locally with Visual Studio Code, first make sure you have the following installed.
+In order to work with the Umbraco source code locally, first make sure you have the following installed.
 
--   [Visual Studio Code](https://code.visualstudio.com/)
+-   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/)
 -   [dotnet SDK v9+](https://dotnet.microsoft.com/en-us/download)
 -   [Node.js v20+](https://nodejs.org/en/download/)
 -   npm v10+ (installed with Node.js)
 -   [Git command line](https://git-scm.com/download/)
 
-Open the root folder of the repository in Visual Studio Code.
+### Familiarizing yourself with the code
+
+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.
 
-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`.
+There are two web projects in the solution with client-side assets based on TypeScript, `Umbraco.Web.UI.Client` and `Umbraco.Web.UI.Login`.
 
-You can also run the tasks manually on the command line:
+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.
+
+Here are some suggestions based on how we work on developing Umbraco at HQ.
+
+### First checkout
+
+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.
 
 ```
-cd src\Umbraco.Web.UI.Client
-npm i
-npm run build:for:cms
+cd <solution root>\src\Umbraco.Web.UI
+dotnet run --no-build
 ```
 
-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.
+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.
+
+### Back-end only changes
 
-The login screen is a different frontend build, for that one you can run it as follows:
+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.
+
+Go to `Umbraco.Cms.StaticAssets.csproj` and comment out the following lines of MsBuild by adding a REM statement in front:
 
 ```
-cd src\Umbraco.Web.UI.Login
-npm i
-npm run dev
+REM npm ci --no-fund --no-audit --prefer-offline
+REM npm run build:for:cms
 ```
 
-If you just want to build the Login screen to `Umbraco.Web.UI` then instead of running `dev`, you can do: `npm run build`.
+Just be careful not to include this change in your PR.
+
+### Front-end only changes
 
-To run the C# portion of the project, either hit <kbd>F5</kbd> to begin debugging, or manually using the command line:
+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`:
 
 ```
-dotnet watch --project .\src\Umbraco.Web.UI\Umbraco.Web.UI.csproj
+"BackOfficeHost": "http://localhost:5173",
+"AuthorizeCallbackPathName": "/oauth_complete",
+"AuthorizeCallbackLogoutPathName": "/logout",
+"AuthorizeCallbackErrorPathName": "/error"
 ```
 
-**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.**
+Then run Umbraco from the command line.
 
-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.
+```
+cd <solution root>\src\Umbraco.Web.UI
+dotnet run --no-build
+```
 
-#### Debugging with Visual Studio
+In another terminal window, run the following to watch the front-end changes and launch Umbraco using the URL indicated from this task.
 
-In order to build the Umbraco source code locally with Visual Studio, first make sure you have the following installed.
+```
+cd <solution root>\src\Umbraco.Web.UI.Client
+npm run dev:server
+```
 
--   [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)
--   [Node.js v20+](https://nodejs.org/en/download/)
--   npm v10+ (installed with Node.js)
--   [Git command line](https://git-scm.com/download/)
+You'll find as you make changes to the front-end files, the updates will be picked up and your browser refreshed automatically.
+
+> [!NOTE]
+> 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 easiest way to get started is to open `umbraco.sln` in Visual Studio.
+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:
 
-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.
+```
+cd <solution root>\src\Umbraco.Web.UI.Login
+npm run build
+```
 
-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.
+In both front-end projects, if you've refreshed your branch from the latest on GitHub you may need to update front-end dependencies.
 
-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.
+To do that, run:
 
-**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.**
+```
+npm ci --no-fund --no-audit --prefer-offline
+```
+
+### Full-stack changes
+
+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.
+
+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:
+
+```
+cd <solution root>\src\Umbraco.Web.UI.Client
+npm run generate:server-api-dev
+```
 
-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.
+Please also update the `OpenApi.json` file held in the solution by copying and pasting the output from `/umbraco/swagger/management/swagger.json`.
 
 ## Building from source
 
@@ -148,5 +186,4 @@ The produced artifacts are published in a container that can be downloaded from
 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).
 
 [ 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"

.github/CONTRIBUTING.md

@@ -4,34 +4,43 @@
 
 These contribution guidelines are mostly just that - guidelines, not rules. This is what we've found to work best over the years, but if you choose to ignore them, we still love you! 💖 Use your best judgement, and feel free to propose changes to this document in a pull request.
 
-## Getting Started
 We have a guide on [what to consider before you start](contributing-before-you-start.md) and more detailed guides at the end of this article.
 
-The following steps are a quick-start guide:
+## Contribution guide
+
+This guide describes each step to make your first contribution:
 
 1. **Fork**
 
     Create a fork of [`Umbraco-CMS` on GitHub](https://github.com/umbraco/Umbraco-CMS)
-    
+
     ![Fork the repository](img/forkrepository.png)
-    
+
 2. **Clone**
 
     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`.
-    
-    ![Clone the fork](img/clonefork.png) 
-    
+
+    ![Clone the fork](img/clonefork.png)
+
 3. **Switch to the correct branch**
 
     Switch to the `contrib` branch
 
-4. **Build**
+4. **Branch out**
+
+    Create a new branch based on `contrib` and name it after the issue you're fixing, For example: `v15/bugfix/18132-rte-tinymce-onchange-value-check`.
+
+    Please follow this format for branches: `v{major}/{feature|bugfix|task}/{issue}-{description}`. 
+
+    This is a development branch for the particular issue you're working on, in this case a bug-fix for issue number `18132` that affects Umbraco v.15.
+
+    Don't commit to `contrib`, create a new branch first.
 
-    Build your fork of Umbraco locally [as described in the build documentation](BUILD.md), you can build with any IDE that supports dotnet or the command line.
+5. **Build or run a Development Server**
 
-5. **Branch**
+    You can build or run a Development Server with any IDE that supports DotNet or the command line.
 
-    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.
+    Read [Build or run a Development Server](BUILD.md) for the right approach to your needs.
 
 6. **Change**
 
@@ -41,7 +50,7 @@ The following steps are a quick-start guide:
 
     Done? Yay! 🎉
 
-    Remember to commit to your new `temp` branch, and don't commit to `contrib`. Then you can push the changes up to your fork on GitHub.
+    Remember to commit to your branch. When it's ready push the changes to your fork on GitHub.
 
 8. **Create pull request**
 

.github/workflows/test-backoffice.yml

@@ -43,6 +43,8 @@ jobs:
       - name: Check for circular dependencies
         run: node devops/circular/index.js src
       - run: npm run lint:errors
+      - run: npm run generate:tsconfig
+      - run: npm run generate:icons
       - run: npm run build:for:cms
       - run: npm run check:paths
       - run: npm run generate:jsonschema:dist