# Contributing <!-- omit in toc -->

First of all, thank you for contributing to Fab City OS! The goal of this document is to provide everything you need to know in order to contribute to Fab City OS.

- [🚩 Assumptions](#-assumptions)
- [🚧 How to Contribute](#-how-to-contribute)
- [🎮 Setup a development environment](#-setup-a-development-environment)
- [👩‍💻 Development Workflow](#-development-workflow)
- [🌐 Realease Workflow](#-realease-workflow)

## 🚩 Assumptions

1. **You're familiar with [Kubernetes](https://kubernetes.io/docs/tutorials/kubernetes-basics/) and [Helm](https://helm.sh/docs/)**
2. **You're familiar with [Gitlab](https://about.gitlab.com/learn/) and the [Merge Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)(PR) workflow.**
3. **You've read the Fab City OS [documentation](https://www.interfacerproject.eu/) and the [README](/README.md).**
4. **You know about the Fab City OS [community](https://matrix.to/#/#fcos:fabcity.hamburg). Please use this for help.**

## 🚧 How to Contribute

1. Make sure that the contribution you want to make is explained or detailed in a Gitlab issue! Find an [existing issue](https://gitlab.fabcity.hamburg/software/fab-city-os-core-chart/-/issues) or [open a new one](https://gitlab.fabcity.hamburg/software/fab-city-os-core-chart/-/issues/new).
2. Once done, [fork the Fab City OS Core Chart repository](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html) in your Gitlab account. Ask a maintainer if you want your issue to be checked before making a PR.
3. [Create a new Git branch](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-new-branch).
4. Review the [Development Workflow](#development-workflow) section that describes the steps to maintain the repository.
5. Make the changes on your branch.
6. [Submit the branch as a PR](https://docs.gitlab.com/ee/user/project/merge_requests/index.html) pointing to the `main` branch of the main fab-city-os-core-chart repository. A maintainer should comment and/or review your Pull Request within a few days. Although depending on the circumstances, it may take longer.<br>
   We do not enforce a naming convention for the PRs, but **please use something descriptive of your changes**, having in mind that the title of your PR will be automatically added to the next [release changelog](https://gitlab.fabcity.hamburg/software/fab-city-os-core-chart/releases/).

## 🎮 Setup a development environment

In order to use the different tools on this repository, you will first need to:

- [Install GNU Make](https://www.gnu.org/doc/doc.html) on your machine. This allows you to execute our predefined subset of commands with the `make` command.

- [Install Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) on your machine. This will allow you to run commands against your Kubernetes cluster with the `kubectl` command.

- [Install Helm](https://helm.sh/docs/intro/install/). This will allow you to run the `helm` command, enabling the installation and manipulation of Helm charts.

- [Install k3d](https://k3d.io/#installation). This will allow you to bootstrap creating a local Kubernetes cluster with the `k3d` command.

- [Optional: Use the Nix Package Manager](https://nix.dev/tutorials/install-nix). This will allow you to make use of the [nixpkgs](https://Gitlab.com/NixOS/nixpkgs), automatically managing all required dependencies from the [`nix develop`](shell.nix). In addition you also need the [nixpkgs: direnv](https://search.nixos.org/packages?query=direnv) for automatic environment selection.

## 👩‍💻 Development Workflow

1. 🔀 [Fork the Project](https://gitlab.fabcity.hamburg/software/fab-city-os-core-chart/-/forks/new)
2. Check out `make help`
3. Create your feature branch `git checkout -b feature/branch`
4. Start the development Cluster `make up`
5. Make your changes
6. Validate chart rendering `make dry-run`
7. 📋 Testing and Linting `make lint`
8. Install the chart `make install`
9. 🐛 Watch all resources to be fully applied `make watch-all`
10. Commit your changes `git commit -am 'Add some fooBar'`
11. Push to the branch `git push origin feature/branch`
12. 🙏 Thank you

> Please note that when deploying the helm chart during development, there may be a situation where the `zenflow` container crashes constantly. In this case, please rebuild the `k3d` development environment to delete any leftover `postgres` configuration.

## 🌐 Realease Workflow

1. Install the helm plugins `make get-plugins`
2. Add the Gitlab repository `helm repo add fab-city-os-core-beta https://gitlab.fabcity.hamburg/api/v4/projects/248/packages/helm/beta`
3. Build the package `make build`
4. Push the package to Gitlab `make push`

Thank you again for reading this through, we can not wait to begin to work with you if you made your way through this contributing guide 😍.