# CONTRIBUTING
So you've decided to actively join the development of EaseProbe!!! First let us Welcome you and **Thank You** for your interest.

The following document will try to provide some general guidelines and information about the development processes to help your on-boarding experience.

This document is constantly under change with new things been added as the project grows.

## General guidelines
The following are some guidelines that will help in getting your code contributions easier accepted.

* For the Coding Standard, we follow [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md).
* Write a small description for your PR, this makes it much easier for the reviewer
* Make sure to address any linting or test failures your PR introduces
* If you contribute a new feature
* update or create appropriate tests for it
* update the README accordingly
* If you introduced new files make sure to include the license on top of each new `.go` file. Simply run `resources/scripts/copyright.sh` script can help to add the open source license.

## How EaseProbe Works

Basically, the EaseProbe have the following major code organization.

### 1) Probe

- **Probe Interface**. Every Probe must implement the `Probe` interface, which is defined in `probe/probe.go`
- **Base Probe**. The `probe/base/base.go` help to implement most `Probe` interface methods, like a Probe framework.
- **Concrete Probe**. Every concrete probe must do the following works
- `Config()` - provide probe's `kind`, `tag` and other information.
- `DoProbe()` - implement the actual code that does the probing.
- **Probe Configuration**. The probe configuration need to be added in` Conf` struct ( `conf/conf.go` ).
- **Probe Result** The probe result and the relevant statistics are stored in a `Result` object, this is define in `probe/result.go`

### 2) Notify

- **Notify Interface**. Every Notify must implement the `Notify` interface, which is defined in `notify/notify.go`.
- **Base Notify**. The `notify/base/base.go` help to implement most `Notify` interface methods, like a Notify framework.
- **Concrete Notify**. Every concrete notifier must do the following works
- `Config()` - provide notify's `kind`, report format, send function and other information.
- `SendXXXNotification(title, message)` - provide the implementation of how the notifier will perform the notification.
- **Formation**. The formatting of the notification message, such as HTML, Markdown, JSON, Text or use a completely custom formatter. These formations are defined in `report/result.go`

### 3) Channel

The Channel is used for connect the Probe and Notify. The `channel` package organize the Probe and Notify associations.

- **Probe**. All of the prober will be run by `runProbers()` function in `cmd/easeprobe/probe.go`
- **Notify**. The Notify would watch the Probe's Result in `channel.WatchAllEvents()` which in `channel/manager.go`.

### 4) SLA Report

The SLA Report contains the results of all Probers which include:

- **SLA Data**. SLA data (in `probe/data.go`) that are (optionally) persistent in a file.
- **Web Server**. the Web server for SLA report is in `web` package, it includes the HTML web page and the Restful API. This uses of Chi framework.
- **Report Format**. there are serveral foramtion for SLA report, the code is in `report/sla.go`
- **Scheduler**. take care of the SLA report sceduling requirements such as Daily/Weekly/Monthly and can be found in `cmd/easeprobe/report.go`

### 5) Metrics (Prometheus)

EaseProbe support to export the probe metrics to prometheus. The package `metric/prometheus.go` help to create and register the metric.

- **Base Metrics**. We implement some common metrics for all of Probers i `probe/base/metrics.go` - Total Probe Times(Counter), Probe Duration(Gauge), Status(Gauge), and SLA(Gauge).
- **Customize Metrics**. If we need to deal with the Prober specifice metrics, we can do the following works
- **Define Metrics**. just create the `metrics.go` in probe which define the metrics struct and how to create it.
- **Initialize Metrics**. intial the metrics in `Probe.Config()`funciton
- **Export Metrics**. new a `Probe.ExportMetrics()` function and call it in `Probe.DoProbe()` function.

Examples
- Host Probe metrics: `probe/host/metrics.go`
- HTTP Probe metrics: `probe/http/metrics.go`

## Source Code Files
* `cmd/easeprobe` This is the `main` package for the EaseProbe main function.
* `main.go` - `main()` function to do everything.
* `probe.go` - Initalize and configure the Probers and start up all of probers
* `notify.go` - Initalize and configure the Notifiers.
* `channel.go` - Initalize and configure the Channels.
* `report.go` - SLA report.
* `conf`. This pacakge is for EaseProbe configuration and Log file.
* `conf.go` - EaseProbe configuration file processing.
* `log.go` - EaseProbe application log and access log.
* `daemon`. This pacakge is about EaseProbe daemon operations, like: create the pid file.
* `daemon.go` - For all platform
* `daemon_windows.go` - For Windows platform
* `daemon_linux.go` - For Linux Platform
* `daemon_unix.go` - For all non-Windows and non-Linux platform.
* `global`. This package defines the Global variables, structures and functions.
* `global.go` - Default Value, Retry, TLS structure, Working Directory...
* `easeprobe.go` - EaseProbe Name, Icon, Version, Host information.
* `probe.go` - The common configuration for all Probers.
* `notify.go` - The common configuration for all Notifiers.
* `metric`. This package is for external metric report, like prometheus.
* `prometheus.go` - The warpper of prometheus metrics export.
* `channel`. Channel object and management
* `channel.go` - The channel object.
* `manager.go` - manage all of channels
* `notify`. All of notifiers
* `notify.go` - The notify interface definition.
* `base/` - The notify framework for all notify.
* `probe`. All of probers.
* `probe.go` - the probe interface definition.
* `base/` - The probe framework for all notification
* `result.go` - The probe result object, includes all of the probe result, like status, start probe time, round trip time, statistics, etc.
* `data.go` - The probe result persistent.
* `status.go` - The probe status definition: `StatusUp`, `StatusDown`, `StatusUnknown`, ... etc.
* `report`. SLA Report formation.
* `types.go` - The format of report
* `sla.go` - SLA report for all of format.
* `result.go`- Probe Result for all of format.
* `web`. This package is the web server for EaseProbe SLA report and API
* `server.go` - Web Server
* `log.go` - Access Log
​
## Makefile
The project provides a `Makefile` with the following targets
* `build`: compile the project and produce the EaseProbe binary
* `test`: runs `go test`
* `docker`: builds the docker images for EaseProbe (using `resources/Dockerfile`)
* `clean`: cleans up files created during build
​
​
## Github Actions
The project currently has 2 Github Workflows that are responsible for checking the code and assisting in releases of new versions.

- `ci.yaml` would do license checking, code lint, and unit test.
- `release.yaml` would do release work, build the binaries and docker images.

**Note**: goreleaser configuraiton file is `.goreleaser.yaml`, and it would use the `resources/Dockerfile.goreleaser` for docker image.

​
### CI (`.github/workflows/ci.yaml`)
The workflow has two jobs `lint` & `test`
​
The `lint` job runs the following
- Spelling Check with Reviewdog
- Linting through Revive
- Check formatting with **`gofmt`**
​
The `test` job runs the following
- `go test -cover -race`