chore: add protoc, rpc provider doc, FAQ

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "spec"]
 	path = spec
 	url = https://github.com/open-feature/spec.git
+[submodule "schemas"]
+	path = schemas
+	url = [email protected]:open-feature/schemas.git

Makefile

@@ -9,6 +9,8 @@ ZD_CLIENT_IMG ?= zd-client:latest
 FLAGD_PROXY_IMG ?= flagd-proxy:latest
 FLAGD_PROXY_IMG_ZD ?= flagd-proxy:zd
 
+DOCS_DIR ?= web-docs
+
 workspace-init: workspace-clean
 	go work init
 	$(foreach module, $(ALL_GO_MOD_DIRS), go work use $(module);)
@@ -107,6 +109,17 @@ markdownlint:
 markdownlint-fix:
 	$(MDL_CMD) --entrypoint="markdownlint-cli2-fix" davidanson/markdownlint-cli2-rules:$(MDL_DOCKER_VERSION) "**/*.md"
 
+.PHONY: pull-schemas-submodule
+pull-schemas-submodule:
+	git submodule update schemas
+
+.PHONY: generate-proto-docs
+generate-proto-docs: pull-schemas-submodule
+	docker run --rm -v ${PWD}/$(DOCS_DIR)/reference/specifications:/out -v ${PWD}/schemas/protobuf:/protos pseudomuto/protoc-gen-doc --doc_opt=markdown,protos-with-toc.md schema/v1/schema.proto sync/v1/sync_service.proto \
+	&& echo '<!-- WARNING: THIS DOC IS AUTO-GENERATED. DO NOT EDIT! -->' > ${PWD}/$(DOCS_DIR)/reference/specifications/protos.md \
+	&& sed '/^## Table of Contents/,/#top/d' ${PWD}/$(DOCS_DIR)/reference/specifications/protos-with-toc.md >> ${PWD}/$(DOCS_DIR)/reference/specifications/protos.md \
+	&& rm -f ${PWD}/$(DOCS_DIR)/reference/specifications/protos-with-toc.md
+
 .PHONY: run-web-docs
-run-web-docs: generate-docs
+run-web-docs: generate-docs generate-proto-docs
 	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

mkdocs.yml

@@ -69,10 +69,9 @@ nav:
     - 'Providers': 'reference/providers.md'
     - 'Monitoring': 'reference/monitoring.md'
     - 'Specifications':
-      - 'Flag Evaluation Protocol': 'reference/specifications/flag-evaluation-protocol.md'
-      - 'Flag Sync Protocol': 'reference/specifications/flag-sync-protocol.md'
       - 'RPC Providers': 'reference/specifications/rpc-providers.md'
       - 'In-Process Providers': 'reference/specifications/in-process-providers.md'
+      - 'Protobuf schemas': 'reference/specifications/protos.md' 
       - 'Custom Operations':
         - 'Fractional Specification': 'reference/specifications/custom-operations/fractional-operation-spec.md'
         - 'Semantic Version Specification': 'reference/specifications/custom-operations/semver-operation-spec.md'

web-docs/faq.md

@@ -0,0 +1,36 @@
+# Frequently Asked Questions
+
+> Why do I need this? Can't I just use envronment variables?
+
+Feature-flags are not environment varianles.
+If you don't need to update your flag values without restarting your application, target specific users, randomly assign values for experimentation, or perform scheduled roll-outs, you don't need feature flags and you can probably use simple static configuration.
+
+For more information on feature-flagging concepts, see [feature-flagging](./concepts/feature-flagging.md).
+
+---
+
+> Why is it called "flagd"?
+
+Please see [naming](./reference/naming.md).
+
+---
+
+> What is flagd's relationship to OpenFeature?
+
+flagd is fully [OpenFeature-compliant](./concepts/feature-flagging.md#openfeature-compliance).
+
+---
+
+> How do I run flagd?
+
+You can run flagd as a standalone application, accessible over HTTP or gRPC, or you can embed it into your application.
+Please see [architecture](./architecture.md) and [deployment](./deployment.md) for more information.
+
+---
+
+> Why doesn't flagd support {_my desired feature_}?
+
+Because you haven't opened a PR or created an issue!
+
+We're always adding new functionality to flagd, and welcome additions and ideas from new contributors.
+Don't hesitate to [open an issue](https://github.com/open-feature/flagd/issues)!

web-docs/reference/providers.md

@@ -0,0 +1,9 @@
+# Providers
+
+flagd was built from the ground up to be [Openfeature-compliant](../concepts/feature-flagging.md#openfeature-compliance).
+To use it in your application, you must use the [OpenFeature SDK](https://openfeature.dev/docs/reference/technologies/) for your language, along witht the associated OpenFeature _provider_.
+For more information about Openfeature providers, see the [OpenFeature documentation](https://openfeature.dev/docs/reference/concepts/provider).
+
+Providers for flagd come in two flavors: those that are built to communicate with a flagd instance (over HTTP or gRPC) and those that embed flagd's evaluation engine directly (note that some providers are capable of operating in either mode). For more information on how to deploy and use flagd, see [architecture](../architecture.md) and [deployment](../deployment.md).
+
+For a catalog of available flagd providers, check out the [OpenFeature ecosystem](https://openfeature.dev/ecosystem?instant_search%5Bquery%5D=flagd&instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Provider) page.

web-docs/reference/specifications/in-process-providers.md

@@ -32,7 +32,7 @@ Other sources may be desired eventually, so separation of concerns should be mai
 ## gRPC sources
 
 gRPC sync sources are identified by the `provider` field set to `grpc`.
-When such a sync source is specified, the in-process flagd provider should connect to the gRPC service located at the `uri` of the sync source, and use its `sync` API ([see here](https://github.com/open-feature/schemas)) to retrieve the feature flag definition.
+When such a sync source is specified, the in-process flagd provider should connect to the gRPC service located at the `uri` of the sync source, and use its [sync API](./protos.md#syncv1sync_serviceproto) to retrieve the feature flag definition.
 If the `selector` field of the sync source is set, that selector should be passed through to the `Sync` and `FetchAllFlags` requests sent to the gRPC server.
 
 ### Protobuf