From 8d2acc833d7e9e45e826e7a796223b955843fc36 Mon Sep 17 00:00:00 2001 From: Karthikeyan Chinnakonda Date: Tue, 8 Feb 2022 13:21:10 +0530 Subject: [PATCH] server: add a note about experimental features PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3598 GitOrigin-RevId: e7f8d2f8d1b9490f0e28e59073f7b6a62447c04c --- server/src-lib/Hasura/Server/Init/Config.hs | 28 +++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/server/src-lib/Hasura/Server/Init/Config.hs b/server/src-lib/Hasura/Server/Init/Config.hs index 30f8a99e558..0b5baac82e2 100644 --- a/server/src-lib/Hasura/Server/Init/Config.hs +++ b/server/src-lib/Hasura/Server/Init/Config.hs @@ -114,6 +114,33 @@ $( J.deriveJSON instance Hashable API +{- Note: [Experimental features] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The graphql-engine accepts a list of experimental features that can be +enabled at the startup. Experimental features are a way to introduce +new, but not stable features to our users in a manner in which they have +the choice to enable or disable a certain feature(s). + +The objective of an experimental feature should be that when the feature is disabled, +the graphql-engine should work the same way as it worked before adding the said feature. + +The experimental feature's flag is `--experimental-features` and the corresponding +environment variable is `HASURA_GRAPHQL_EXPERIMENTAL_FEATURES` which expects a comma-seperated +value. + +When an experimental feature is stable enough i.e. it's stable through multiple non-beta releases +then we make the feature not experimental i.e. it will always be enabled. Note that when we do this +we still have to support parsing of the experimental feature because users of the previous version +will have it enabled and when they upgrade an error should not be thrown at the startup. For example: + +The inherited roles was an experimental feature when introduced and it was enabled by +setting `--experimental-features` to `inherited_roles` and then it was decided to make the inherited roles +a stable feature, so it was removed as an experimental feature but the code was modified such that +`--experimental-features inherited_roles` to not throw an error. + +-} + data RawServeOptions impl = RawServeOptions { rsoPort :: Maybe Int, rsoHost :: Maybe HostPreference, @@ -152,6 +179,7 @@ data RawServeOptions impl = RawServeOptions rsoEventsFetchBatchSize :: Maybe NonNegativeInt, rsoGracefulShutdownTimeout :: Maybe Seconds, rsoWebSocketConnectionInitTimeout :: Maybe Int + -- see Note [Experimental features] } -- | @'ResponseInternalErrorsConfig' represents the encoding of the internal