diff --git a/.github/BUILD.md b/.github/BUILD.md index 82a9b1e217fc..2e081548fee4 100644 --- a/.github/BUILD.md +++ b/.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. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 80a277679c94..b2e6ac484fd9 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -4,10 +4,11 @@ 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** @@ -25,18 +26,22 @@ The following steps are a quick-start guide: Switch to the `contrib` branch -4. **Build** - - 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. +4. **Branch out** -5. **Branch** + 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`. - 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`. + Please follow this format for branches: `v{major}/{feature|bugfix|task}/{issue}-{description}`. - 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. + 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. +5. **Build or run a Development Server** + + You can build or run a Development Server with any IDE that supports DotNet or the command line. + + Read [Build or run a Development Server](BUILD.md) for the right approach to your needs. + 6. **Change** Make your changes, experiment, have fun, explore and learn, and don't be afraid. We welcome all contributions and will [happily give feedback](contributing-first-issue.md#questions). @@ -45,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** diff --git a/src/Umbraco.Web.UI.Client/.github/README.md b/src/Umbraco.Web.UI.Client/.github/README.md index d1e27aa2b06c..cf76fd68ef7c 100644 --- a/src/Umbraco.Web.UI.Client/.github/README.md +++ b/src/Umbraco.Web.UI.Client/.github/README.md @@ -1,23 +1,21 @@ -# Umbraco.Web.UI.Client +# Guide for working with Umbraco Backoffice UI/Client -This is the Umbraco Backoffice UI/Client, also known as Bellissima. - -This is for you as a contributor who likes to make changes to the Backoffice UI/Client project. +This is for you as a contributor who would like to make changes to the Backoffice UI project. ## Installation 1. Make sure you have [NodeJS](https://nodejs.org/en/download) installed. 2. Run `npm install` to install the dependencies. -## Ways to run a Development Server +## Ways to run a Front-end Development Server -1. If you will be working from VS Code, there is options to run both [back-end and front-end server in debug modes](#debug-via-vs-code). +A. If you will be working from VS Code, there is a script to [run the servers in debug mode](#debug-via-vs-code). -2. Or you can choose to [run each of these individually](#run-a-front-end-server-against-a-local-umbraco-instance), this can be done from the Command-line/Terminal, but requires a few lines from configuration on the back-end server. +B. Otherwise choose to [run the servers individually](#run-a-front-end-server-against-a-local-umbraco-instance). ### Debug via VS Code -If you are using VS Code, you can use the `launch.json` file to start the development server. This will also start the Umbraco instance and open the browser. +Open the project with VS Code, then under `Run and Debug`, you can use the `launch.json` file to start the development server. This will also start the Umbraco instance and open the browser. You should run the task **Backoffice Launch (Vite + .NET Core)** in the **Run and Debug** panel, which will start the Vite server and the Umbraco instance. It automatically configures Umbraco (using environment variables) to use the Vite server as the Backoffice host. This task will also open a browser window, so you can start developing right away. The first time you run this task, it will take a little longer to start the Umbraco instance, but subsequent runs will be faster. Keep an eye on the Debug Console to see when the Umbraco instance is ready and then refresh the browser. @@ -25,13 +23,13 @@ If you want to run the Vite server only, you can run the task **Backoffice Launc If you have an existing Vite server running, you can run the task **Backoffice Attach Vite** to attach the debugger to the Vite server. -### Run a front-end server against a local Umbraco instance - +### Run a Front-end server against a local Umbraco instance -To enable the client running on a different server, we need to correct the `appsettings.json` of your project. +#### 1. Configure Umbraco instance +Enable the front-end server communicating with the Backend server(Umbraco instance) you need need to correct the `appsettings.json` of your project. -For code contributions you can use the backend project of `src/Umbraco.Web.UI`. -Open this file in an editor: `src/Umbraco.Web.UI/appsettings.Development.json` and add these 4 fields to the `Umbraco > CMS > Security`: +For code contributions use the backend project of `/src/Umbraco.Web.UI`. +Open this file in an editor: `/src/Umbraco.Web.UI/appsettings.Development.json` and add these 4 fields to the `Umbraco > CMS > Security`: ```json "Umbraco": { @@ -48,11 +46,11 @@ Open this file in an editor: `src/Umbraco.Web.UI/appsettings.Development.json` a This will override the backoffice host URL, enabling the Client to run from a different origin. -Then start the backend server by running the command: `dotnet run` in the `Umbraco.Web.UI` folder. - -#### Run the front-end server +#### 2. Start Umbraco +Then start the backend server by running the command: `dotnet run` in the `/src/Umbraco.Web.UI` folder. -Now start the Vite server by running the command: `npm run dev:server` in the `Umbraco.Web.UI.Client` folder. +#### 3. Start Frontend server +Now start the frontend server by running the command: `npm run dev:server` in the `/src/Umbraco.Web.UI.Client` folder. Finally open `http://localhost:5173` in your browser. @@ -70,7 +68,7 @@ The documentation can be found on [Umbraco Docs](https://docs.umbraco.com/umbrac ### Storybook -You can test the Storybook locally by running `npm run storybook`. This will start the Storybook server and open a browser window with the Storybook UI. +You can test the Backoffice UI Storybook locally by running `npm run storybook`. This will start the server and open a browser window with the Storybook Web Interface. Storybook is an excellent tool to test out UI components in isolation and to document them. It is also a great way to test the responsiveness and accessibility of the components.