GITBOOK-199: improve Development section

SUMMARY.md

@@ -85,6 +85,7 @@
 * [Sponsors](about/sponsors.md)
 * [Development](about/development/README.md)
   * [Code standards](about/development/code-standards.md)
+  * [Contribute](about/development/contribute.md)
   * [Environment](about/development/environment.md)
   * [Localization](about/development/localization.md)
 * [Credits](about/credits.md)

about/development/code-standards.md

@@ -1,12 +1,17 @@
+---
+description: >-
+  Mainsail's code standards ensure consistent, readable, and maintainable code.
+  Learn best practices for style, naming, and commit messages to contribute
+  effectively to the project's quality.
+---
+
 # Code standards
 
 ## Code formatting <a href="#code-formatting" id="code-formatting"></a>
 
-For the formatting we currently use [Prettier](https://prettier.io/). This is an opinionated code formatter which makes sure that we use the same formatting across the whole codebase. To make sure that this is complied with every PR, there is a Github Workflow which checks this on all PRs.
-
-You can always run `npm run format` to make sure that all your changes are formatted correctly.
+We use [Prettier](https://prettier.io/) as our code formatter to ensure consistent formatting across the entire codebase. Prettier is an opinionated tool that enforces a unified style. To maintain this consistency, every pull request (PR) is automatically checked by a GitHub Workflow.
 
-To make it easier, you can use the integrations of the Jetbrains IDE / VSCode applications.
+Before submitting your PR, you can run `npm run format` to ensure that all your changes are properly formatted. To streamline this process, consider using Prettier integrations available in [JetBrains IDEs](code-standards.md#jetbrains-ide) or [VSCode](code-standards.md#vscode).
 
 ### Jetbrains IDE <a href="#jetbrains-ide" id="jetbrains-ide"></a>
 
@@ -19,7 +24,7 @@ Add this integration by:
 
 So it looks like this:
 
-![](../../../.gitbook/assets/prettier-config-jetbrains.png)
+![](../../.gitbook/assets/prettier-config-jetbrains.png)
 
 ### VSCode <a href="#vscode" id="vscode"></a>
 
@@ -28,6 +33,10 @@ Add this integration by:
 * Adding the [prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
 * Setting the `editor.defaultFormatter` preference to `esbenp.prettier-vscode`
 
+## **Commit Messages**
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for our commit messages. This system uses a structured format that makes it easy to understand the purpose of each commit. A typical commit message should include a type (such as `feat`, `fix`, or `docs`), a brief description, and optionally, additional details in the body. Following this convention helps in keeping a clean and manageable commit history, making it easier to track changes and generate changelogs.
+
 ## Linting <a href="#linting" id="linting"></a>
 
 For linting we use [ESLint](https://eslint.org/). Which statically analyzes our application for common problems. Just like our code formatting, this is also checked in every PR using a custom workflow.

about/development/contribute.md

@@ -0,0 +1,87 @@
+---
+description: >-
+  We welcome contributions to Mainsail! Whether fixing bugs, adding features, or
+  improving documentation, your help is invaluable. Please follow these
+  guidelines to ensure a smooth process.
+---
+
+# Contribute
+
+## Familiarize Yourself with the Code Standards
+
+Before contributing, make sure to review the Mainsail [Code Standards](code-standards.md). Adhering to these standards helps maintain code quality and consistency across the project. Key areas include:
+
+* **Coding Style:** Follow the project's conventions for formatting and structure.
+* **Commit Messages:** Write clear and concise commit messages that describe the changes you've made.
+* **Documentation:** Ensure that your code is well-documented, and update any relevant sections of the project documentation.
+
+## Fork and Clone the Repository
+
+If you haven't already, fork the Mainsail repository on GitHub to create a personal copy of the project. Then, clone your fork to your local machine:
+
+```bash
+git clone https://github.com/YOUR-GITHUB-USERNAME/mainsail.git
+cd mainsail
+```
+
+{% hint style="info" %}
+If you need help to setup your Environment, please follow this [guide](environment.md).
+{% endhint %}
+
+## Create a New Branch
+
+Always create a new branch for your work rather than making changes directly on the main branch. Use a descriptive name for your branch that reflects the work you're doing:
+
+```bash
+git checkout -b your-feature-branch
+```
+
+## Make Your Changes
+
+Implement your changes while following the Mainsail code standards. Be sure to test your changes thoroughly in your local development environment.
+
+## Commit Your Changes
+
+Once your changes are ready, stage and commit them to your branch. Use meaningful commit messages:
+
+```bash
+git add .
+git commit -m "Description of the changes made"
+```
+
+{% hint style="info" %}
+We follow the [Conventional Commits](code-standards.md#commit-messages) specification for writing commit messages. This means your commit message should start with a type (like `feat`, `fix`, or `docs`), followed by a short, descriptive summary of the change. For example:\
+
+
+`git commit -m "feat: add new user login feature"`
+
+\
+Following this format ensures that our commit history is clear and organized, which helps with tracking changes and generating release notes.
+{% endhint %}
+
+## Push Your Branch to GitHub
+
+After committing your changes, push your branch to your GitHub fork:
+
+```bash
+git push origin your-feature-branch
+```
+
+## Create a Pull Request
+
+Once your branch is pushed, go to the Mainsail repository on GitHub and open a Pull Request (PR) from your branch. In your PR description, include the following:
+
+* **PR Title:** Ensure that your PR title follows the [Conventional Commits](code-standards.md#commit-messages) schema. Since we use squash and merge, the PR title will become the commit message in the Mainsail commit history.
+* **Problem Description:** Clearly describe the issue or feature your PR addresses.
+* **Solution Overview:** Provide an overview of the changes you made and why.
+* **How to Test:** Include detailed instructions on how to test your changes.
+* **Screenshots:** Upload screenshots or gifs to demonstrate the feature or fix, especially for UI changes.
+* **Link to Issues:** If your PR resolves a specific issue, mention it by linking to the issue.
+
+## Respond to Feedback
+
+Mainsail maintainers will review your PR. Be prepared to make adjustments based on feedback. Once approved, your changes will be merged into the main project.
+
+## Celebrate Your Contribution!
+
+After your PR is merged, your contributions become part of Mainsail. Thank you for helping to improve the project!

about/development/environment.md

@@ -1,79 +1,113 @@
 ---
-description: Set up a development environment for Mainsail
+description: >-
+  Learn how to set up a local development environment for Mainsail on your PC.
+  This guide walks you through the process so you can start developing and
+  customizing quickly.
 ---
 
 # Environment
 
-## Set up the environment <a href="#set-up-the-environment" id="set-up-the-environment"></a>
+Whether new to Mainsail development or looking to optimize your existing setup, this guide provides clear instructions for installing the necessary tools and configuring your environment. We will show you how to install the required dependencies, set up your development environment, and take the first steps towards customizing your Mainsail project efficiently.
 
-At this point you should have already forked Mainsail into your repositories.\
-If that is not the case, go ahead and fork Mainsail now.
+## Prerequisites
 
-Copy the `.env.development.local.example` file and omit the `.example` at the end.\
-The file is located in the root directory of the Mainsail project.
+Before you start setting up your development environment, make sure you have the following prerequisites.
 
-Now edit the `.env.development.local` file to reflect your printers network configuration.
+### **Install Git**
 
-_Example:_ If the IP of your printer is `192.168.1.10`, modify it like this:
+Git is a version control system that you'll need to clone the Mainsail repository to manage your changes. Download Git from the official [Git website](https://git-scm.com/) and install it according to the instructions for your operating system.
 
-```editorconfig
-# hostname or ip from the moonraker instance
-VUE_APP_HOSTNAME=192.168.1.10
-```
+### **Install Node.js**
+
+Node.js is a JavaScript runtime environment required for developing and building Mainsail. Download and install the latest LTS version of Node.js from the [official website](https://nodejs.org/). Ensure npm (the Node Package Manager) is installed along with Node.js.
 
 {% hint style="info" %}
-You need to set `VUE_APP_HOSTNAME=localhost` in case you want to use a [Virtual-Klipper-Printer](environment.md#virtual-klipper-printer-with-docker).
+Ensure that you are using Node.js version 20 or higher.
 {% endhint %}
 
-### Configure Moonraker <a href="#configure-moonraker" id="configure-moonraker"></a>
+### **Fork and Clone the Mainsail Repository**
 
-For Moonraker, you need to add localhost:8080 to the `cors_domains` section inside the `moonraker.conf`:
+Fork the Mainsail repository on GitHub to create a copy of the project in your own GitHub account. Visit the [Mainsail GitHub page](https://github.com/mainsail-crew/mainsail) and click on "Fork." Afterward, you can clone your forked repository to your local machine using Git. Use the following command in your terminal:
 
-```yaml
-cors_domains:
-    *//localhost:8080
+```bash
+git clone https://github.com/YOUR-GITHUB-USERNAME/mainsail.git
 ```
 
-{% hint style="info" %}
-Port 8080 is the default port `npm` will serve the development server on.
-{% endhint %}
+## Mainsail Development Server
+
+After successfully cloning the Mainsail repository, the next step is to set up and start the development server. Follow these steps:
+
+### Install npm Dependencies
+
+Use `npm ci` in your project directory to install all the necessary dependencies for the project. This command ensures that the exact versions of packages specified in the `package-lock.json` file are installed:
 
-### Install NodeJS <a href="#install-nodejs" id="install-nodejs"></a>
+```bash
+npm ci
+```
 
-You can download NodeJS from [here](https://nodejs.org/en/download).\
-Pick your preferred installation package.
+### Configure the .env file
+
+Mainsail uses a .env file to define environment variables. Copy the `.env.development.local.example` file in the project's root directory, rename it `.env.development.local`, and adjust the configurations to suit your needs. Here is an example of what the `.env.development.local` file might look like:
+
+```yaml
+# hostname or ip from the moonraker instance
+VUE_APP_HOSTNAME=printer.local
+
+# port from the moonraker instance
+VUE_APP_PORT=7125
+
+# route_prefix from the moonraker instance
+VUE_APP_PATH="/"
+
+# reconnect interval in ms
+VUE_APP_RECONNECT_INTERVAL=5000
+
+# where should mainsail read the instances from (moonraker, browser or json)
+VUE_APP_INSTANCES_DB="moonraker"
+
+# defaults for multi language tests
+VUE_APP_I18N_LOCALE=en
+VUE_APP_I18N_FALLBACK_LOCALE=en
+```
 
 {% hint style="info" %}
-Make sure you run node >= 16
+You need to set `VUE_APP_HOSTNAME=localhost` in case you want to use a [Virtual-Klipper-Printer](environment.md#virtual-klipper-printer-with-docker).
 {% endhint %}
 
-Open your preferred terminal application and navigate into the Mainsail root directory.\
-Run the following command to install all required modules and dependencies:
+### **Add `cors_domains` to Moonraker**
 
-```bash
-npm install
+To ensure the development server can access the Moonraker API, add the `cors_domains` entry \`\*//localhost:8080\` in the Moonraker configuration file (`moonraker.conf`). Open the configuration file and add the line at the end of `cors_domains`. Your `moonraker.conf` should look like this:
+
+```yaml
+[authorization]
+cors_domains:
+    https://my.mainsail.xyz
+    http://my.mainsail.xyz
+    http://*.local
+    http://*.lan
+    *://localhost:8080
 ```
 
-Afterwards run the following command to start a local development server:
+### **Start the Development Server**
+
+To start the Mainsail development server and test the application locally, run the following command:
 
 ```bash
 npm run serve
 ```
 
-Once the server is up and running, you can access Mainsail on `http://localhost:8080`.
-
-## Virtual-Klipper-Printer with Docker <a href="#virtual-klipper-printer-with-docker" id="virtual-klipper-printer-with-docker"></a>
+This command will start the development server, and you should be able to open Mainsail in your default browser at [http://localhost:8080](http://localhost:8080). The server will respond to code changes and automatically refresh the components/page.
 
-It is possible to develop Mainsail with a virtual printer running inside a Docker container.\
-We created a special project for that, which you can find [here](https://github.com/mainsail-crew/virtual-klipper-printer).
+## Virtual Klipper Printer with Docker (Optional)
 
-To use our Virtual-Klipper-Printer project, it is required to have Docker installed.\
-Below are some general resources on how to get Docker.
+For those who wish to develop Mainsail using a virtual printer, it's possible to set up a virtual Klipper printer within a Docker container. We've created a dedicated project to simplify this process, which you can find [https://github.com/mainsail-crew/virtual-klipper-printer](https://github.com/mainsail-crew/virtual-klipper-printer).
 
-**Linux:** [https://docs.docker.com/engine/install](https://docs.docker.com/engine/install)\
-**Mac:** [https://docs.docker.com/docker-for-mac/install](https://docs.docker.com/docker-for-mac/install)\
-**Windows:** [https://docs.docker.com/docker-for-windows/install](https://docs.docker.com/docker-for-windows/install)
+Before proceeding, ensure that Docker is installed on your system. Docker allows you to run applications in isolated containers, making it an ideal tool for testing and development.
 
+**Docker Installation Resources:**
 
+* **Linux:** [Install Docker on Linux](https://docs.docker.com/engine/install)
+* **Mac:** [Install Docker on Mac](https://docs.docker.com/docker-for-mac/install)
+* **Windows:** [Install Docker on Windows](https://docs.docker.com/docker-for-windows/install)
 
-After Docker is installed, follow the instructions [here](https://github.com/mainsail-crew/virtual-klipper-printer#instructions) to get everything up and running.
+Once Docker is installed, follow the instructions in the virtual Klipper printer project repository to set up and run your virtual printer environment.