Table of Contents
- [Setting up the Development Environment](#setting-up-the-development-environment)
- [Local Development](#local-development-)
- [Gitpod](#gitpod-)
- [NixOS Dev Shell using Nix Flake](#nixos-dev-shell-using-nix-flake-)
- [Local Development with Docker Compose](#local-development-with-docker-compose-)
- [Project Commands](#project-commands)
- [Environmental Variables](#environmental-variables)
- [Git Strategy](#git-strategy)
- [Flow](#git-flow)
- [Branches](#git-branch-naming)
- [Commit emojis](#commit-emojis)
- [PR Guidelines](#pr-guidelines)
- [Resources for Beginners](#resources-for-beginners)
- [App Info](#app-info)
- [Code Style Guide](#style-guide)
- [Application Structure](#application-structure)
- [Development Tools](#development-tools)
- [Misc / Notes](#notes)
## Setting up the Development Environment
By default, we provide four different ways to work on the project. Which are as follows:
- [Local Development](#local-development-)
- [Gitpod](#gitpod-)
- [NixOS Dev Shell using Nix Flake](#nixos-dev-shell-using-nix-flake-)
- [Local Development with Docker Compose](#local-development-with-docker-compose-)
The diferent methods are explained in depth below.
### Local Development
This section covers how to setup the project for development on your local machine (bare metal).
#### Prerequisites
Before you start working on the project. You will need the following packages installed on your system:
- A latest version of `cargo` installed on your system which is required to manage building and running the project. The installation instruction for this can be found [here](https://doc.rust-lang.org/cargo/getting-started/installation.html).
- A latest version of `npm` installed on your system which is required to allow the installation of other tools necessary for the project. The installation for this can be found [here](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
- A latest version of `redis` installed on your system which will be used to avoid introducing unexpected issue when working on the project. The installation for this can be found [here](https://redis.io/docs/getting-started/installation/).
- A latest version of `stylelint` should be installed on your system which will be used by the pre-commit checks to lint the code before a commit can be made to ensure better code quality. Before you install `stylelint` on your system, make sure you have `npm` installed on you system. To install `stylelint` run the following command:
```shell
$ npm i -g stylelint
```
> **Note**
> In the above command the dollar sign(**$**) refers to running the command in privilaged mode by using utilities `sudo`, `doas`, `pkgexec` or any other privilage access methods.
- `Cargo-watch` installed on your system which will allow to auto build the project when any checks occur in the source code files in the codebase (`websurfx` directory). Before you install `cargo-watch` on your system, make sure you have `cargo` installed on your system. To install `cargo-watch` run the following command:
```shell
cargo install cargo-watch
```
- `Git` installed on your system. The installation instruction for this can be found [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
- Finally, A latest version of `Docker` installed on your system which will be used to avoid introducing unexpected issue when working on the project. The installation instructions for this can be found [here](https://docs.docker.com/engine/install/).
> **Note**
> For **rolling release linux distributions (distros)**, the above mentioned all required packages except for `stylelint` and `cargo-watch` can also be installed via the distro specific package manager.
>
> **For Example:**
>
> On `arch linux` the following packages could be installed by following link to the installation instructions provided down below:
>
> - `Cargo`: https://wiki.archlinux.org/title/rust
> - `Npm`: https://wiki.archlinux.org/title/Node.js
> - `Redis`: https://wiki.archlinux.org/title/redis
> - `Git`: https://wiki.archlinux.org/title/git
> - `Docker`: https://wiki.archlinux.org/title/docker
>
> But we do not recommend this method for **stable release linux distros** as they tend to not provide very up to date versions of the required packages.
#### Setting up Pre-commit Checks
Before you setup `pre-commit` checks, you will first need to clone **your fork of the project** and navigate into the cloned repository by running the following command:
```shell
git clone https://github.com/