update doc

Signed-off-by: Thomas Poignant <[email protected]>
thomaspoignant · thomaspoignant · Oct 12, 2022 · Jul 28, 2022 · Jul 28, 2022 · Jul 29, 2022
commit c3f782dd7e212a484b84e261f26771cab67579b9
diff --git a/README.md b/README.md
@@ -30,7 +30,7 @@ go get github.com/thomaspoignant/go-feature-flag
 ```
 ## What is go-feature-flag?
 
-A simple and complete feature flag solution, without any complex backend system to install, all you need is a file as your backend.
+GO Feature Flag is the easiest way to start with feature flag without any complex backend system to install, all you need is a file as your backend.
 
 No server is needed, just add a file to your central system and all your services will react to the changes in this file.
 
@@ -58,7 +58,7 @@ _The code of this demo is available in [`thomaspoignant/go-feature-flag-demo`](h
 
 ## Can I use GO Feature Flag with another language?
 
-Originally GO Feature Flag was built to be a GOlang only library, but it limits the ecsystem too much.  
+Originally GO Feature Flag was built to be a GOlang only library, but it limits the ecosystem too much.  
 To be compatible with more language we have implemented the [GO Feature Flag Relay Proxy](https://github.com/thomaspoignant/go-feature-flag-relay-proxy).
 It is a service you can host that provides an API to evaluate your flags, you can call it using HTTP to get your variation.
 
@@ -169,57 +169,89 @@ If you prefer to do it manually please follow instruction bellow.
 <summary>YAML</summary>
 
 ```yaml
-test-flag:
-  percentage: 100
-  rule: key eq "random-key"
-  true: true
-  false: false
-  default: false
-  disable: false
-  trackEvents: true
-  version: 1
-  rollout:
-    experimentation:
-      start: 2021-03-20T00:00:00.10-05:00
-      end: 2021-03-21T00:00:00.10-05:00
-
-  test-flag2:
-    rule: key eq "not-a-key"
-    percentage: 100
-    true: true
-    false: false
-    default: false
-    version: 12
+# This is your configuration for your first flag
+first-flag:
+  variations: # All possible return value for your feature flag
+    A: false
+    B: true
+  targeting: # If you want to target a subset of your users in particular
+    - query: key eq "random-key"
+      percentage:
+        A: 0
+        B: 100
+  defaultRule: # When no targeting match we use the defaultRule
+    variation: A
+
+# A second example of a flag configuration
+second-flag:
+  variations:
+    A: "valueA"
+    B: "valueB"
+    defaultValue: "a default value"
+  targeting:
+    - name: legacyRuleV0
+      query: key eq "not-a-key"
+      percentage:
+        A: 10
+        B: 90
+  defaultRule:
+    name: legacyDefaultRule
+    variation: defaultValue
+  version: "12"
+  experimentation: 
+    start: 2021-03-20T00:00:00.1-05:00
+    end: 2021-03-21T00:00:00.1-05:00
 ```
 </details>
 <details>
 <summary>JSON</summary>
 
 ```json
 {
-  "test-flag": {
-    "percentage": 100,
-    "rule": "key eq \"random-key\"",
-    "true": true,
-    "false": false,
-    "default": false,
-    "disable": false,
-    "trackEvents": true,
-    "version": 1,
-    "rollout": {
-      "experimentation": {
-        "start": "2021-03-20T05:00:00.100Z",
-        "end": "2021-03-21T05:00:00.100Z"
+  "first-flag": {
+    "variations": {
+      "A": false,
+      "B": true
+    },
+    "targeting": [
+      {
+        "query": "key eq \"random-key\"",
+        "percentage": {
+          "A": 0,
+          "B": 100
+        }
       }
+    ],
+    "defaultRule": {
+      "variation": "A"
     }
   },
-  "test-flag2": {
-    "rule": "key eq \"not-a-key\"",
-    "percentage": 100,
-    "true": true,
-    "false": false,
-    "default": false,
-    "version": 12
+
+  "second-flag": {
+    "variations": {
+      "A": "valueA",
+      "B": "valueB",
+      "defaultValue": "a default value"
+    },
+    "targeting": [
+      {
+        "name": "legacyRuleV0",
+        "query": "key eq \"not-a-key\"",
+        "percentage": {
+          "A": 10,
+          "B": 90
+        }
+      }
+    ],
+    "defaultRule": {
+      "name": "legacyDefaultRule",
+      "variation": "defaultValue"
+    },
+    "version": "12",
+    "experimentation": {
+      "start": "2021-03-20T05:00:00.100Z",
+      "end": "2021-03-21T05:00:00.100Z"
+    }
   }
 }
 ```
@@ -230,29 +262,43 @@ test-flag:
 <summary>TOML</summary>
 
 ```toml
-[test-flag]
-percentage = 100.0
-rule = "key eq \"random-key\""
-true = true
-false = false
-default = false
-disable = false
-trackEvents = true
-version = 1.0
-
-[test-flag.rollout]
-
-  [test-flag.rollout.experimentation]
+[first-flag.variations]
+A = false
+B = true
+
+[[first-flag.targeting]]
+query = 'key eq "random-key"'
+
+  [first-flag.targeting.percentage]
+  A = 0
+  B = 100
+
+[first-flag.defaultRule]
+variation = "A"
+
+[second-flag]
+version = "12"
+
+  [second-flag.variations]
+  A = "valueA"
+  B = "valueB"
+  defaultValue = "a default value"
+
+  [[second-flag.targeting]]
+  name = "legacyRuleV0"
+  query = 'key eq "not-a-key"'
+
+    [second-flag.targeting.percentage]
+    A = 10
+    B = 90
+
+  [second-flag.defaultRule]
+  name = "legacyDefaultRule"
+  variation = "defaultValue"
+
+  [second-flag.experimentation]
   start = 2021-03-20T05:00:00.100Z
   end = 2021-03-21T05:00:00.100Z
-
-[test-flag2]
-rule = "key eq \"not-a-key\""
-percentage = 100.0
-true = true
-false = false
-default = false
-version = 12.0
 ```
 
 </details>
@@ -261,7 +307,7 @@ All the fields to create a flag are described in the [documentation](https://doc
 
 ## Rule format
 
-The rule format is based on the [`nikunjy/rules`](https://github.com/nikunjy/rules) library.
+The query format is based on the [`nikunjy/rules`](https://github.com/nikunjy/rules) library.
 
 All the operations can be written capitalized or lowercase (ex: `eq` or `EQ` can be used).  
 Logical Operations supported are `AND` `OR`.

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -10,18 +10,18 @@ During the initialization you must give a [`ffclient.Config{}`](https://pkg.go.d
 
 ## Configuration fields
 
-| Field | Description |
-|---|---|
-|`Retriever`  | The configuration retriever you want to use to get your flag file<br/> *See [Store your flag file](flag_file/index.md) for the configuration details*.|
-|`Context`  | *(optional)*<br/>The context used by the retriever.<br />Default: `context.Background()`|
-|`Environment`  | <a name="option_environment"></a>*(optional)*<br/>The environment the app is running under, can be checked in feature flag rules.<br />Default: `""`<br/>*Check [**"environments"** section](../flag_format/#environments) to understand how to use this parameter.*|
-|`DataExporter` | *(optional)*<br/>DataExporter defines how to export data on how your flags are used.<br/> *see [export data section](data_collection/index.md) for more details*.|
-|`FileFormat`| *(optional)*<br/>Format of your configuration file. Available formats are `yaml`, `toml` and `json`, if you omit the field it will try to unmarshal the file as a `yaml` file.<br/>Default: `YAML`|
-|`Logger`   | *(optional)*<br/>Logger used to log what `go-feature-flag` is doing.<br />If no logger is provided the module will not log anything.<br/>Default: No log|
-|`Notifiers` | *(optional)*<br/>List of notifiers to call when your flag file has been changed.<br/> *See [notifiers section](./notifier/index.md) for more details*.|
-|`PollingInterval`   | (optional) Duration to wait before refreshing the flags.<br/>The minimum polling interval is 1 second.<br/>Default: 60 * time.Second|
-|`StartWithRetrieverError` | *(optional)* If **true**, the SDK will start even if we did not get any flags from the retriever. It will serve only default values until the retriever returns the flags.<br/>The init method will not return any error if the flag file is unreachable.<br/>Default: **false**|
-|`Offline`| *(optional)* If **true**, the SDK will not try to retrieve the flag file and will not export any data. No notification will be send neither.<br/>Default: false|
+| Field                     | Description                                                                                                                                                                                                                                                                      |
+|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Retriever`               | The configuration retriever you want to use to get your flag file<br/> *See [Store your flag file](flag_file/index.md) for the configuration details*.                                                                                                                           |
+| `Context`                 | *(optional)*<br/>The context used by the retriever.<br />Default: `context.Background()`                                                                                                                                                                                         |
+| `Environment`             | <a name="option_environment"></a>*(optional)*<br/>The environment the app is running under, can be checked in feature flag rules.<br />Default: `""`<br/>*Check [**"environments"** section](../flag_format/#environments) to understand how to use this parameter.*             |
+| `DataExporter`            | *(optional)*<br/>DataExporter defines how to export data on how your flags are used.<br/> *see [export data section](data_collection/index.md) for more details*.                                                                                                                |
+| `FileFormat`              | *(optional)*<br/>Format of your configuration file. Available formats are `yaml`, `toml` and `json`, if you omit the field it will try to unmarshal the file as a `yaml` file.<br/>Default: `YAML`                                                                               |
+| `Logger`                  | *(optional)*<br/>Logger used to log what `go-feature-flag` is doing.<br />If no logger is provided the module will not log anything.<br/>Default: No log                                                                                                                         |
+| `Notifiers`               | *(optional)*<br/>List of notifiers to call when your flag file has been changed.<br/> *See [notifiers section](./notifier/index.md) for more details*.                                                                                                                           |
+| `PollingInterval`         | (optional) Duration to wait before refreshing the flags.<br/>The minimum polling interval is 1 second.<br/>Default: 60 * time.Second                                                                                                                                             |
+| `StartWithRetrieverError` | *(optional)* If **true**, the SDK will start even if we did not get any flags from the retriever. It will serve only default values until the retriever returns the flags.<br/>The init method will not return any error if the flag file is unreachable.<br/>Default: **false** |
+| `Offline`                 | *(optional)* If **true**, the SDK will not try to retrieve the flag file and will not export any data. No notification will be send neither.<br/>Default: false                                                                                                                  |
 
 ## Example
 ```go linenums="1"

diff --git a/docs/data_collection/file.md b/docs/data_collection/file.md
@@ -27,11 +27,11 @@ ffclient.Config{
 
 ## Configuration fields
 
-| Field  | Description  |
-|---|---|
-|`OutputDir`   | OutputDir is the location of the directory where to store the exported files.<br/>It should finish with a `/`.  |
-|`Format`   |   _(Optional)_ Format is the output format you want in your exported file.<br/>Available format: **`JSON`**, **`CSV`**.<br/>**Default: `JSON`** |
-|`Filename`   | _(Optional)_ Filename is the name of your output file.<br/>You can use a templated config to define the name of your exported files.<br/>Available replacement are `{{ .Hostname}}`, `{{ .Timestamp}}` and `{{ .Format}}`<br/>**Default: `flag-variation-{{ .Hostname}}-{{ .Timestamp}}.{{ .Format}}`**|
-|`CsvTemplate`   | _(Optional)_ CsvTemplate is used if your output format is CSV.<br/>This field will be ignored if you are using another format than CSV.<br/>You can decide which fields you want in your CSV line with a go-template syntax, please check [internal/exporter/feature_event.go](https://github.com/thomaspoignant/go-feature-flag/blob/main/internal/exporter/feature_event.go) to see what are the fields available.<br/>**Default:** `{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}}\n` |
+| Field         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `OutputDir`   | OutputDir is the location of the directory where to store the exported files.<br/>It should finish with a `/`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `Format`      | _(Optional)_ Format is the output format you want in your exported file.<br/>Available format: **`JSON`**, **`CSV`**.<br/>**Default: `JSON`**                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `Filename`    | _(Optional)_ Filename is the name of your output file.<br/>You can use a templated config to define the name of your exported files.<br/>Available replacement are `{{ .Hostname}}`, `{{ .Timestamp}}` and `{{ .Format}}`<br/>**Default: `flag-variation-{{ .Hostname}}-{{ .Timestamp}}.{{ .Format}}`**                                                                                                                                                                                                                                                     |
+| `CsvTemplate` | _(Optional)_ CsvTemplate is used if your output format is CSV.<br/>This field will be ignored if you are using another format than CSV.<br/>You can decide which fields you want in your CSV line with a go-template syntax, please check [internal/exporter/feature_event.go](https://github.com/thomaspoignant/go-feature-flag/blob/main/internal/exporter/feature_event.go) to see what are the fields available.<br/>**Default:** `{{ .Kind}};{{ .ContextKind}};{{ .UserKey}};{{ .CreationDate}};{{ .Key}};{{ .Variation}};{{ .Value}};{{ .Default}}\n` |
 
 Check the [godoc for full details](https://pkg.go.dev/github.com/thomaspoignant/go-feature-flag/exporter/fileexporter).