[FFM-3363]: Tidy up readme to align with other server SDKs

README.md

@@ -1,55 +1,125 @@
-# Before you Begin
+Harness Feature Flag Golang SDK
+========================
+
+[![Go Report Card](https://goreportcard.com/badge/github.com/drone/ff-golang-server-sdk)](https://goreportcard.com/report/github.com/drone/ff-golang-server-sdk)
+
+## Table of Contents
+**[Intro](#Intro)**<br>
+**[Requirements](#Requirements)**<br>
+**[Quickstart](#Quickstart)**<br>
+**[Further Reading](docs/further_reading.md)**<br>
+**[Build Instructions](docs/build.md)**<br>
+
+
+## Intro
 
 Harness Feature Flags (FF) is a feature management solution that enables users to change the software’s functionality, without deploying new code. FF uses feature flags to hide code or behaviours without having to ship new versions of the software. A feature flag is like a powerful if statement.
+* For more information, see https://harness.io/products/feature-flags/
+* To read more, see https://ngdocs.harness.io/category/vjolt35atg-feature-flags
+* To sign up, https://app.harness.io/auth/#/signup/
 
-For more information, see https://harness.io/products/feature-flags/
+![FeatureFlags](./docs/images/ff-gui.png)
 
-To read more, see https://ngdocs.harness.io/category/vjolt35atg-feature-flags
+## Requirements
+[Golang 1.6](https://go.dev/doc/install) or newer (go version)<br>
 
-To sign up, https://app.harness.io/auth/#/signup/
+## Quickstart
+The Feature Flag SDK provides a client that connects to the feature flag service, and fetches the value
+of featue flags.   The following section provides an example of how to install the SDK and initalize it from
+an application.
+This quickstart assumes you have followed the instructions to [setup a Feature Flag project and have created a flag called `harnessappdemodarkmode` and created a server API Key](https://ngdocs.harness.io/article/1j7pdkqh7j-create-a-feature-flag#step_1_create_a_project).
 
+### Install the SDK
+Install the golang SDK using go
+```golang
+go get github.com/harness/ff-golang-server-sdk
+```
 
-# Harness FFM Server-side SDK for Go
+### A Simple Example
+Here is a complete example that will connect to the feature flag service and report the flag value every 10 seconds until the connection is closed.  
+Any time a flag is toggled from the feature flag service you will receive the updated value.
 
-[![Go Report Card](https://goreportcard.com/badge/github.com/drone/ff-golang-server-sdk)](https://goreportcard.com/report/github.com/drone/ff-golang-server-sdk)
 
-## FFM overview
-FFM is feature flag management platform for helping teams to deliver better software and faster.
+```go
+package main
 
-## Supported GO versions
-This version of FFM has been tested with GO 1.14
+import (
+	"log"
+	"os"
+	"time"
 
-## Install
-`go get github.com/harness/ff-golang-server-sdk`
+	harness "github.com/harness/ff-golang-server-sdk/client"
+	"github.com/harness/ff-golang-server-sdk/evaluation"
+)
 
-## Usage
-First we need to import lib with harness alias
-```golang
-import harness "github.com/harness/ff-golang-server-sdk/client"
-```
+var (
+	flagName string = getEnvOrDefault("FF_FLAG_NAME", "harnessappdemodarkmode")
+	apiKey   string = getEnvOrDefault("FF_API_KEY", "changeme")
+)
 
-Next we create client instance for interaction with api
-```golang
-client, err := harness.NewCfClient(sdkKey)
+func main() {
+	log.Println("Harness SDK Getting Started")
+
+	// Create a feature flag client
+	client, err := harness.NewCfClient(apiKey)
+	if err != nil {
+		log.Fatalf("could not connect to CF servers %s\n", err)
+	}
+	defer func() { client.Close() }()
+
+	// Create a target (different targets can get different results based on rules)
+	target := evaluation.Target{
+		Identifier: "golangsdk",
+		Name:       "GolangSDK",
+		Attributes: &map[string]interface{}{"location": "emea"},
+	}
+
+	// Loop forever reporting the state of the flag
+	for {
+		resultBool, err := client.BoolVariation(flagName, &target, false)
+		if err != nil {
+			log.Fatal("failed to get evaluation: ", err)
+		}
+		log.Printf("Flag variation %v\n", resultBool)
+		time.Sleep(10 * time.Second)
+	}
+
+}
+
+func getEnvOrDefault(key, defaultStr string) string {
+	value := os.Getenv(key)
+	if value == "" {
+		return defaultStr
+	}
+	return value
+}
 ```
 
-Target definition can be user, device, app etc.
-```golang
-target := dto.NewTargetBuilder("key").
- 		Firstname("John").
- 		Lastname("doe").
- 		Email("[email protected]").
- 		Country("USA").
- 		Custom("height", 160).
- 		Build()
+### Running the example
+
+```bash
+export FF_API_KEY=<your key here>
+go run examples/getting_started.go
 ```
 
-Evaluating Feature Flag
-```golang
-showFeature, err := client.BoolVariation(featureFlagKey, &target, false)
+### Running with docker
+If you dont have the right version of golang installed locally, or don't want to install the dependencies you can
+use docker to quick get started
+
+```bash 
+export FF_API_KEY=<your key here>
+docker run -e FF_API_KEY=$FF_API_KEY -v $(pwd):/app -w /app golang:1.17 go run examples/getting_started.go
 ```
 
-Flush any changes and close the SDK
-```golang
-client.close()
-```
+### Additional Reading
+
+Further examples and config options are in the further reading section:
+
+[Further Reading](docs/further_reading.md)
+
+
+-------------------------
+[Harness](https://www.harness.io/) is a feature management platform that helps teams to build better software and to
+test features quicker.
+
+-------------------------

docs/build.md

@@ -0,0 +1,31 @@
+# Building ff-golang-server-sdk
+
+This document shows the instructions on how to build and contribute to the SDK.
+
+## Requirements
+[Golang 1.6](https://go.dev/doc/install) or newer (go version)<br>
+
+## Install Dependencies
+
+```bash
+go mod tidy
+```
+
+## Build the SDK
+Some make targets have been provided to build and package the SDK
+
+```bash
+go build ./...
+```
+
+## Executing tests
+```bash
+ go test -race -v --cover ./...
+```
+
+## Linting and Formating
+To ensure the project is correctly formatted you can use the following commands
+```bash
+go fmt $(go list ./...)
+go vet ./...
+```

docs/further_reading.md

@@ -0,0 +1,50 @@
+# Further Reading
+
+Covers advanced topics (different config options and scenarios)
+
+## Recommended reading
+
+[Feature Flag Concepts](https://ngdocs.harness.io/article/7n9433hkc0-cf-feature-flag-overview)
+
+[Feature Flag SDK Concepts](https://ngdocs.harness.io/article/rvqprvbq8f-client-side-and-server-side-sdks)
+
+## Setting up your Feature Flags
+
+[Feature Flags Getting Started](https://ngdocs.harness.io/article/0a2u2ppp8s-getting-started-with-feature-flags)
+
+## Other Variation Types
+
+### String Variation
+```golang
+client.StringVariation(flagName, &target, "default_string")
+```
+
+### Number Variation
+```golang
+client.NumberVariation(flagName, &target, -1)
+```
+
+### JSON Variation
+```golang
+client.JSONVariation(flagName, &target, types.JSON{"darkmode": false})
+```
+
+
+## Cleanup
+Call the close function on the client
+
+```golang
+client.Close()
+```
+
+
+## Change default URL
+
+When using your Feature Flag SDKs with a [Harness Relay Proxy](https://ngdocs.harness.io/article/q0kvq8nd2o-relay-proxy) you need to change the default URL.
+You can pass the URLs in when creating the client. i.e.
+
+```golamg
+	client, err := harness.NewCfClient(apiKey,
+		harness.WithURL("https://config.feature-flags.uat.harness.io/api/1.0"),
+		harness.WithEventsURL("https://event.feature-flags.uat.harness.io/api/1.0"))
+```

examples/getting_started.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+	"log"
+	"os"
+	"time"
+
+	harness "github.com/harness/ff-golang-server-sdk/client"
+	"github.com/harness/ff-golang-server-sdk/evaluation"
+)
+
+var (
+	flagName string = getEnvOrDefault("FF_FLAG_NAME", "harnessappdemodarkmode")
+	apiKey   string = getEnvOrDefault("FF_API_KEY", "changeme")
+)
+
+func main() {
+	log.Println("Harness SDK Getting Started")
+
+	// Create a feature flag client
+	client, err := harness.NewCfClient(apiKey)
+	if err != nil {
+		log.Fatalf("could not connect to CF servers %s\n", err)
+	}
+	defer func() { client.Close() }()
+
+	// Create a target (different targets can get different results based on rules)
+	target := evaluation.Target{
+		Identifier: "golangsdk",
+		Name:       "GolangSDK",
+		Attributes: &map[string]interface{}{"location": "emea"},
+	}
+
+	// Loop forever reporting the state of the flag
+	for {
+		resultBool, err := client.BoolVariation(flagName, &target, false)
+		if err != nil {
+			log.Fatal("failed to get evaluation: ", err)
+		}
+		log.Printf("Flag variation %v\n", resultBool)
+		time.Sleep(10 * time.Second)
+	}
+
+}
+
+func getEnvOrDefault(key, defaultStr string) string {
+	value := os.Getenv(key)
+	if value == "" {
+		return defaultStr
+	}
+	return value
+}