Docs velociraptor decide

.travis.yml

@@ -15,14 +15,15 @@ branches:
   - /^v\d+\.\d+(\.\d+)?(-\S*)?$/
 
 stages:
+  - 'Readme-sync-preview'
+  - 'Readme-sync'
   - 'Tests'
   - 'Trigger FSC Tests'
   - 'Test Build using latest tag (no upload)'
   - 'Build, Upload and Publish (draft)'
   - 'Test github release assets'
   - 'Publish (real)'
-  - 'Readme-sync-preview'
-  - 'Readme-sync'
+
 
 jobs:
 
@@ -240,15 +241,19 @@ jobs:
         # we need to be in $TRAVIS_BUILD_DIR in order to run the following git diff properly
         - cd $TRAVIS_BUILD_DIR
 
-        #print which docs changed in this Pull Request (and which therefore we expect to be updated by readme-sync-2 tool):
+        # print which docs changed in this Pull Request (and which therefore we expect to be updated by readme-sync-2 tool):
         - CHANGED_DOCS_FILES=($(git diff --name-only $TRAVIS_COMMIT_RANGE -- docs/readme-sync))
         - echo $CHANGED_DOCS_FILES
 
-        #only if changes were made in the docs/readme-sync repo, trigger this readme-sync stage and sync the docs    
-        - git diff --quiet $TRAVIS_COMMIT_RANGE -- docs/readme-sync || ( cd $HOME/readme-sync2 && npx ts-node sync/index.ts --apiKey $README_SYNC_API_KEY_PREVIEW --version 4.0 --docs $TRAVIS_BUILD_DIR/docs/readme-sync/)
-
+        # only if changes were made in the docs/readme-sync repo, trigger this readme-sync stage and sync the docs
+        # to staging readme project at https://rollouts-sandbox-doc-test.readme.io/docs
 
 
+        # build v3.1 docs  to v 1.0 of readme staging  project
+        - git diff --quiet $TRAVIS_COMMIT_RANGE -- docs/readme-sync/v3.1 || ( cd $HOME/readme-sync2 && npx ts-node sync/index.ts --apiKey $README_SYNC_API_KEY_PREVIEW --version 1.0 --docs $TRAVIS_BUILD_DIR/docs/readme-sync/v3.1)
+        # build v4.0 docs to v 1.5 of staging project
+        - git diff --quiet $TRAVIS_COMMIT_RANGE -- docs/readme-sync/v4.0 || ( cd $HOME/readme-sync2 && npx ts-node sync/index.ts --apiKey $README_SYNC_API_KEY_PREVIEW --version 1.5 --docs $TRAVIS_BUILD_DIR/docs/readme-sync/v4.0)
+
     - stage: 'Readme-sync'
       before_script: skip
       cache: false
@@ -272,9 +277,11 @@ jobs:
         - CHANGED_DOCS_FILES=($(git diff --name-only $TRAVIS_COMMIT_RANGE -- docs/readme-sync))
         - echo $CHANGED_DOCS_FILES
 
-        #only if changes were made in the docs/readme-sync repo, trigger this readme-sync stage and sync the docs    
-        - git diff --quiet $TRAVIS_COMMIT_RANGE -- docs/readme-sync || ( cd $HOME/readme-sync2 && npx ts-node sync/index.ts --apiKey $README_SYNC_API_KEY --version 3.1 --docs $TRAVIS_BUILD_DIR/docs/readme-sync/)
-
+        #only if changes were made in the docs/readme-sync repo, trigger this readme-sync stage and sync the docs  
+        # sync v3.1 docs folder to readme project v 3.1  
+        - git diff --quiet $TRAVIS_COMMIT_RANGE -- docs/readme-sync/v3.1 || ( cd $HOME/readme-sync2 && npx ts-node sync/index.ts --apiKey $README_SYNC_API_KEY --version 3.1 --docs $TRAVIS_BUILD_DIR/docs/readme-sync/v3.1
+        # sync v4.0 docs folder to readme project v 4.0  
+        - git diff --quiet $TRAVIS_COMMIT_RANGE -- docs/readme-sync/v4.0 || ( cd $HOME/readme-sync2 && npx ts-node sync/index.ts --apiKey $README_SYNC_API_KEY --version 4.0 --docs $TRAVIS_BUILD_DIR/docs/readme-sync/v4.0
         #########################################################################################
         # directories/scripts for full SDK-reference-guides, to be implemented after agent docs sync
         #########################################################################################

CHANGELOG.md

@@ -35,14 +35,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   - If there is a need to deploy Agent in docker, then the Host needs to be set to 0.0.0.0. This can be achieved by setting variable `OPTIMIZELY_SERVER_HOST=0.0.0.0`, or setting `server.host` to 0.0.0.0 in config file.
 
 ## [1.3.0] - July 7th, 2020
-- Upgrade to use go-sdk v1.3.0. This adds support for JSON feature variables
+- Upgrade to use go-sdk v1.3.0. This adds support for JSON flag variables
 - Add /debug/pprof endpoints to the admin service
 - Run docker container as non root user
 - Log warnings when HTTPS and authorization are not enabled via configuration
 
 ## [1.2.0] - June 18th, 2020
 - Expose event dispatch URL as a config parameter
-- Return experimentKey and variationKey with feature test decisions
+- Return experimentKey and variationKey with experiment decisions
 - Expose health endpoint for all listeners
 - Update API docs
 - Streamline CI stages
@@ -94,7 +94,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Improve build tooling
 - Add standard metrics registry
 - Update documentation
-- Return 404 when feature or experiment are not found
+- Return 404 when flag or experiment are not found
 - Update event payloads to include Agent name and version
 
 ## [0.10.0] - January 9th, 2020
@@ -109,9 +109,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Add metric visibility into event dispatcher
 - Miscellaneous clean-up and of docs and openapi spec
 - Add top level config package to consolidate configuration
-- Incorporate OptimizelyConfig into feature and experiment models
+- Incorporate OptimizelyConfig into flag and experiment models
 - Add get experiment and list experiment endpoints
-- Add user features endpoint for batched decision responses
+- Add user flag endpoint for batched decision responses
 - Add windows tooling
 - Add credit section to README
 - Improve service shutdown
@@ -142,8 +142,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Actually enable the impression tracking endpoint in the router
 
 ## [0.5.0] - October 24th, 2019
-- Adds GET endpoint for user-based features
-- Adds impression tracking for Feature Tests
+- Adds GET endpoint for user-based flag
+- Adds impression tracking for feature tests (referred to as "A/B tests" after Nov 2020)
 
 ## [0.4.0] - October 23rd, 2019
 - Adds admin endpoints for health, info and metrics
@@ -161,7 +161,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [0.2.0] - October 3rd, 2019
 - Adds Optimizely webhook support
-- Adds full Feature MGMT support
+- Adds full flag MGMT support
 - Adds NSQ for UserEvent message transport
 - Adds support for multiple concurrent SDK keys
 

api/openapi-spec/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   title: Optimizely Agent API
-  description: Optimizely Agent is a stand-alone, open-source microservice that provides major benefits over using Optimizely SDKs in certain use cases. Its REST API offers consolidated and simplified endpoints for accessing all the functionality of Optimizely Full Stack SDKs. Use this API the control experiments (such as a feature tests). For more info, see https://docs.developers.optimizely.com/full-stack/docs/optimizely-agent. 
+  description: Optimizely Agent is a stand-alone, open-source microservice that provides major benefits over using Optimizely SDKs in certain use cases. Its REST API offers consolidated and simplified endpoints for accessing all the functionality of Optimizely Full Stack SDKs. Use this API the control experiments (such as a A/B tests). For more info, see https://docs.developers.optimizely.com/full-stack/docs/optimizely-agent. 
   termsOfService: http://optimizely.com/terms/
   license:
     name: Apache 2.0
@@ -15,7 +15,7 @@ paths:
     get:
       summary: Return the Optimizely config for the given environment
       operationId: getConfig
-      description: Return all available experiment and features definitions for this environment.
+      description: Return all available flag rules and their configurations for this environment.
       responses:
         '200':
           description: Valid response
@@ -54,9 +54,9 @@ paths:
       - $ref: '#/components/parameters/typeParam'
       - $ref: '#/components/parameters/enabledParam'
     post:
-      summary: Activate selected features and experiments for the given user.
+      summary: Activate selected flag rules for the given user.
       operationId: activate
-      description: Returns Optimizely's decision about which features and experiments a given user is exposed to. Optionally sends an impression event to the Optimizely analytics backend for any decision made for an experiment. This endpoint consolidates key functionality from the Full Stack SDKs into one convenient call.
+      description: Returns Optimizely's decision about which flag rules a given user is exposed to. Optionally sends an impression event to the Optimizely analytics backend for any decision made for an experiment. This endpoint consolidates key functionality from the Full Stack SDKs into one convenient call.
       responses:
         '200':
           description: Valid response
@@ -161,7 +161,7 @@ components:
     featureKeyParam:
       in: query
       name: featureKey
-      description: Key for the Optimizely Feature
+      description: Key for the Optimizely flag
       schema:
         type: array
         items:
@@ -170,7 +170,7 @@ components:
       in: query
       name: type
       required: false
-      description: Limit the decisions to either experiment or features
+      description: Limit the decisions to a type of flag rule -- either experiments or deliveries ("features")
       schema:
         type: string
         enum:
@@ -466,8 +466,8 @@ components:
         body:  [
         {
           "enabled": true,
-          "experimentKey": "new_feature_test",
-          "featureKey": "new_feature",
+          "experimentKey": "new_ab_test",
+          "featureKey": "new_flag",
           "type": "feature",
           "userId": "user1",
           "variables": {
@@ -481,7 +481,7 @@ components:
         {
           "enabled": false,
           "experimentKey": "flag_test_2",
-          "featureKey": "test_feature",
+          "featureKey": "test_flag",
           "type": "feature",
           "userId": "user1",
           "variables": {

docs/readme-sync/deploy-as-a-microservice/010 - optimizely-agent.md → docs/readme-sync/v3.1/deploy-as-a-microservice/010 - optimizely-agent.md

@@ -32,7 +32,7 @@ Now *with* Agent, instead of installing the SDK six times, you create just one O
 ## 2. Standardize Access Across Teams
 If you want to deploy Optimizely Full Stack once, then roll out the single implementation across a large number of teams, we recommend using Optimizely Agent. 
 
-By standardizing your teams' access to the Optimizely service, you can better enforce processes and implement governance around feature management and experimentation as a practice.
+By standardizing your teams' access to the Optimizely service, you can better enforce processes and implement governance around flag management and experimentation as a practice.
 
 !["A diagram showing the central and standardized access to the Optimizely Agent service across an arbitrary number of teams.\n(Click to Enlarge)"](https://raw.githubusercontent.com/optimizely/agent/master/docs/images/agent-standardized-access.png)
 
@@ -59,7 +59,7 @@ If time to provide bucketing decisions is a primary concern for you, you may wan
 If your app is constructed as a monolith, embedded SDKs might be easier to install and might be a more natural fit for your application and development practices. 
 
 ## 3. Velocity
-If you’re looking for the fastest way to get a single team up and running with deploying feature management and experimentation, embedding an SDK is the best option for you at first. You can always start using Optimizely Agent later, and it can even be used alongside Optimizely Full Stack SDKs running in another part of your stack.
+If you’re looking for the fastest way to get a single team up and running with deploying flag management and experimentation, embedding an SDK is the best option for you at first. You can always start using Optimizely Agent later, and it can even be used alongside Optimizely Full Stack SDKs running in another part of your stack.
 
 # Best Practices
 While every implementation is different, you can review this section of best practices for tips on these commonly discussed topics.

docs/readme-sync/deploy-as-a-microservice/030 - use-optimizely-agent/index.md → docs/readme-sync/v3.1/deploy-as-a-microservice/030 - use-optimizely-agent/index.md

@@ -11,7 +11,7 @@ updatedAt: "2020-04-08T21:26:30.308Z"
 
 Optimizely Agent provides [APIs](https://library.optimizely.com/docs/api/agent/v1/index.html) that enable experimentation and feature management. Agent provides equivalent functionality to all our SDKs. At its core is the [Optimizely Go SDK](doc:go-sdk). In some cases, however, we’ve updated our APIs to simplify key use cases.
 
-### Manage features
+### Manage flags
 
  Optimizely Agent simplifies the core feature management of our [SDK APIs](doc:sdk-reference-guides).  It consolidates the following endpoints:
 

docs/readme-sync/v4.0/deploy-as-a-microservice/001 - AUTHOR-AGENT-DOCS-IN-GITHUB.md

@@ -0,0 +1,10 @@
+---
+title: "CAUTION - DON'T AUTHOR AGENT DOCS IN README"
+excerpt: ""
+slug: "author-agent-docs-in-github"
+hidden: true
+createdAt: "2020-02-21T17:44:53.019Z"
+updatedAt: "2020-04-13T23:02:34.056Z"
+---
+
+Agent docs sync from Github. So, any changes you author here in Readme will just be overwritten. Make docs updates over in Github. For more info, see [authoring guidelines in github](https://github.com/optimizely/agent/blob/master/docs/internal%20docs%20authoring%20notes.md).

docs/readme-sync/v4.0/deploy-as-a-microservice/010 - optimizely-agent.md

@@ -0,0 +1,78 @@
+---
+title: "Optimizely Agent"
+excerpt: ""
+slug: "optimizely-agent"
+hidden: false
+metadata: 
+  title: "Optimizely Agent microservice - Optimizely Full Stack"
+createdAt: "2020-02-21T20:35:58.387Z"
+updatedAt: "2020-07-14T20:51:52.458Z"
+---
+Optimizely Agent is a standalone, open-source, and highly available microservice that provides major benefits over using Optimizely SDKs in certain use cases. The [Agent REST API](https://library.optimizely.com/docs/api/agent/v1/index.html) offers consolidated and simplified endpoints for accessing all the functionality of Optimizely Full Stack SDKs. 
+
+A typical production installation of Optimizely Agent is to run two or more services behind a load balancer or proxy. The service itself can be run via a Docker container or installed from source. See [Setup Optimizely Agent](doc:setup-optimizely-agent) for instructions on how to run Optimizely Agent.
+
+### Example Implementation
+![example implementation](https://raw.githubusercontent.com/optimizely/agent/master/docs/images/agent-example-implementation.png)
+# Should I Use Optimizely Agent?
+
+Here are some of the top reasons to consider using Optimizely Agent:
+
+## 1. Service Oriented Architecture (SOA)
+If you already separate some of your logic into services that might need to access the Optimizely decision APIs, we recommend using Optimizely Agent. 
+
+The images below compare implementation styles in a service-oriented architecture, first *without* using Optimizely Agent, which shows six SDK embedded instances:
+
+!["A diagram showing the use of SDKs installed on each service in a service oriented architecture \n(Click to Enlarge)"](https://raw.githubusercontent.com/optimizely/agent/master/docs/images/agent-service-oriented-architecture.png)
+
+Now *with* Agent, instead of installing the SDK six times, you create just one Optimizely instance: an HTTP API that every service can access as needed. 
+
+!["A diagram showing the use of Optimizely Agent in a single service \n(Click to Enlarge)"](https://raw.githubusercontent.com/optimizely/agent/master/docs/images/agent-single-service.png)
+
+## 2. Standardize Access Across Teams
+If you want to deploy Optimizely Full Stack once, then roll out the single implementation across a large number of teams, we recommend using Optimizely Agent. 
+
+By standardizing your teams' access to the Optimizely service, you can better enforce processes and implement governance around flag management and experimentation as a practice.
+
+!["A diagram showing the central and standardized access to the Optimizely Agent service across an arbitrary number of teams.\n(Click to Enlarge)"](https://raw.githubusercontent.com/optimizely/agent/master/docs/images/agent-standardized-access.png)
+
+## 3. Networking Centralization
+You don’t want many SDK instances connecting to Optimizely's cloud service from every node in your application. Optimizely Agent centralizes your network connection. Only one cluster of agent instances connects to Optimizely for tasks  like update [datafiles](doc:get-the-datafile) and dispatch [events](doc:track-events).
+
+## 4. Languages
+You’re using a language that isn’t supported by a native SDK (i.e. Elixir, Scala, Perl). While its possible to create your own service using an Optimizely SDK of your choice, you could also customize the open-source Optimizely Agent to your needs without building the service layer on your own. 
+
+
+# Reasons to *not* use Optimizely Agent
+If your use case wouldn't benefit greatly from Optimizely Agent, you should consider the below reasons to *not* use Optimizely Agent and review Optimizely's many [open-source SDKs](doc:sdk-reference-guides) instead. 
+
+## 1. Latency
+If time to provide bucketing decisions is a primary concern for you, you may want to use an embedded Full Stack SDK rather than Optimizely Agent. 
+
+
+| Implementation Option | Decision Latency |
+|-----------------------|------------------|
+| Embedded SDK          | microseconds     |
+| Optimizely Agent      | milliseconds     |
+
+## 2. Monolith
+If your app is constructed as a monolith, embedded SDKs might be easier to install and might be a more natural fit for your application and development practices. 
+
+## 3. Velocity
+If you’re looking for the fastest way to get a single team up and running with deploying flag management and experimentation, embedding an SDK is the best option for you at first. You can always start using Optimizely Agent later, and it can even be used alongside Optimizely Full Stack SDKs running in another part of your stack.
+
+# Best Practices
+While every implementation is different, you can review this section of best practices for tips on these commonly discussed topics.
+
+
+## How many Agent instances should I deploy?
+Agent can scale to large decision / event tracking volumes with relatively low CPU / memory specs. For example, at Optimizely, we scaled our deployment to 740 clients with a cluster of 12 agent instances, which in total use 6 vCPUs and 12GB RAM. You will likely need to focus more on network bandwidth than compute power.
+
+## Using a load balancer
+Any standard load balancer should let you route traffic across your agent cluster. At Optimizely, we used an AWS Elastic Load Balancer (ELB) for our internal deployment. This allows us to transparently scale our agent cluster as internal demands increase.
+
+## Synchronizing datafiles across Agent instances
+Agent offers eventual rather than strong consistency across datafiles.
+In detail, today, each agent instance maintains a dedicated, separate cache. Each agent instance persists an SDK instance for each SDK key your team uses.  Agent instances automatically keep datafiles up to date for each SDK key instance so that you will have eventual consistency across the cluster. The rate of the datafile update can be [set as the configuration](doc:configure-optimizely-agent) value ```OPTIMIZELY_CLIENT_POLLINGINTERVAL```  (the default is 1 minute).
+Because SDKs are generally stateless today, they shouldn’t need to share data. We plan to add a common backing data store, so we invite you to share your feedback. 
+If you require strong consistency across datafiles, then we recommend an active / passive deployment where all requests are made to a single vertically scaled host, with a passive, standby cluster available for high availability.