From 1df3a17af464241cc4af6b92c285619c7736dcd2 Mon Sep 17 00:00:00 2001
From: kevin-kline <21stcenturykline@gmail.com>
Date: Fri, 10 Sep 2021 14:46:53 -0300
Subject: [PATCH] docs: updated gitlab README and plugin README

fixup! docs: updated gitlab README and plugin README
---
 plugins/README.md        | 102 ++++++++++++++++++++++++++++++++++++---
 plugins/gitlab/README.md |   3 +-
 2 files changed, 97 insertions(+), 8 deletions(-)

diff --git a/plugins/README.md b/plugins/README.md
index 9e010492e17..592c9a24d0a 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -1,11 +1,99 @@
-# ⚠️ (WIP) So you want to Build a New Plugin...
+# So you want to Build a New Plugin...
 
 ...the good news is, it's easy!
 
-- [ ] Make new plugin doc with new go setup
 
-  - Basic Interface
-  - Summary
-  - The Collector
-  - The Enricher
-  - Step by Step
+## Basic Interface
+
+```golang
+type YourPlugin string
+
+func (plugin YourPlugin) Description() string {
+	return "To collect and enrich data from YourPlugin"
+}
+
+func (plugin YourPlugin) Execute(options map[string]interface{}, progress chan<- float32) {
+	logger.Print("Starting YourPlugin execution...")
+
+  // Check fields that are needed in options.
+	projectId, ok := options["projectId"]
+	if !ok {
+		logger.Print("projectId is required for YourPlugin execution")
+		return
+	}
+
+  // Start collecting stuff.
+  if err := tasks.CollectProject(projectId); err != nil {
+		logger.Error("Could not collect projects: ", err)
+		return
+	}
+  // Handle error.
+  if err != nil {
+    logger.Error(err)
+  }
+
+  // Export a variable named PluginEntry for Framework to search and load
+  var PluginEntry YourPlugin //nolint
+}
+```
+
+## Summary
+
+  To build a new plugin you will need a few things. You should choose an API that you'd like to see data from. Think about the metrics you would like to see first, and then look for data that can support those metrics.
+
+## Collection
+
+  Then you will want to write a collection to gather data. You will need to do some reading of the API documentation to figure out what metrics you will want to see at the end in your Grafana dashboard (configuring Grafana is the final step).
+
+## Build a Fetcher to make Requests
+
+The plugins/core folder contains an api client that you can implement within your own plugin. It has useful methods like Get(). 
+Each API handles pagination differently, so you will likely need to implement a "fetch with pagination" method. One way to do
+this is to use the "ants" package as a way to manage tasks concurrently: https://github.com/panjf2000/ants
+
+Your colection methods may look something like this:
+
+```golang
+func Collect() error {
+	pluginApiClient := CreateApiClient()
+
+	return pluginApiClient.FetchWithPagination("<your_api_url>",
+		func(res *http.Response) error {
+			pluginApiResponse := &ApiResponse{}
+      // You must unmarshal the response from the api to use the results.
+			err := core.UnmarshalResponse(res, pluginApiResponse)
+			if err != nil {
+				logger.Error("Error: ", err)
+				return nil
+			}
+      // loop through the results and save them to the database.
+			for _, value := range *pluginApiResponse {
+				pluginModel := &models.pluginModel{
+					pluginId:       value.pluginId,
+					Title:          value.Title,
+					Message:        value.Message,
+				}
+
+				err = lakeModels.Db.Clauses(clause.OnConflict{
+					UpdateAll: true,
+				}).Create(&pluginModel).Error
+
+				if err != nil {
+					logger.Error("Could not upsert: ", err)
+				}
+			}
+
+			return nil
+		})
+}
+```
+
+Note the use of "upsert". This is useful for only saving modified records.
+
+## Enrichment
+
+  Once you have collected data from the API, you may want to enrich that data by:
+
+  - Add fields you don't currently have
+  - Compute fields you might want for metrics
+  - Eliminate fields you don't need
diff --git a/plugins/gitlab/README.md b/plugins/gitlab/README.md
index ea990514ce8..23c11404c3e 100644
--- a/plugins/gitlab/README.md
+++ b/plugins/gitlab/README.md
@@ -7,11 +7,12 @@ Metric Name | Description
 Pull Request Count | Number of Pull/Merge Requests
 Pull Request Pass Rate | Ratio of Pull/Merge Review requests to merged
 Pull Request Reviewer Count | Number of Pull/Merge Reviewers
-Pull Request Review Time | Time from the first Pull/Merge Review comment until merged
+Pull Request Review Time | Time from Pull/Merge created time until merged
 Commit Author Count | Number of Contributors
 Commit Count | Number of Commits
 Added Lines | Accumulated Number of New Lines
 Deleted Lines | Accumulated Number of Removed Lines
+Pull Request Review Rounds | Number of cycles of commits followed by comments/final merge
 
 ## Configuration