From 8e58d9b4da9d4828577765080228c22111d64f37 Mon Sep 17 00:00:00 2001 From: navneel mandal Date: Fri, 26 Apr 2024 22:26:14 +0530 Subject: [PATCH 01/12] enh: add documentation for snap-in build config --- fern/docs/pages/references/build_config.mdx | 60 +++++++++++++++++++++ fern/docs/pages/references/manifest.mdx | 31 +++++++++-- 2 files changed, 88 insertions(+), 3 deletions(-) create mode 100644 fern/docs/pages/references/build_config.mdx diff --git a/fern/docs/pages/references/build_config.mdx b/fern/docs/pages/references/build_config.mdx new file mode 100644 index 00000000..4a420a0f --- /dev/null +++ b/fern/docs/pages/references/build_config.mdx @@ -0,0 +1,60 @@ +Build config is a way to provide data to the snap-in build process. Currently, the only way to send data +is through environment variables that the build process has access to. + +This is useful if the developer wants to import libraries from a different registry or wants to use private packages that +require authentication token. + +## Specifying the Config + +Build config is defined as: + +```yaml +build_config: + environment_variables: + - name: + description: + type: + value: +``` + +For example, to import a library that use the GitHub NPM registry, we should add +the following variables to the build config + +```yaml +build_config: + environment_variables: + - name: REGISTRY_NAME + description: Name of the github registry to import the library. + type: constant + value: npm.pkg.github.com + - name: AUTH_TOKEN + description: Token to access the registry + type: keyring + value: access_token +``` + +Since AUTH_TOKEN is a sensitive informantion that should not be hardcoded in the manifest, +the developer can instead mention the name of the developer keyring and during snap-in version creation +time, provide the developer keyring to take the value from. + +```yaml +developer_keyrings: + - name: access_token + description: Access token for the GitHub registry + display_name: Access Token +``` + +## Using the variables defined in config + +## Private Registries + +If the package is present in private registries, the developer can update the `.npmrc` file in the `code` folder from the template to include the URL of the registry and the token. + +For example, to use variables defined in manifest defined in the previous section, the `.npmrc` file will look something like this: + +```.npmrc +@githubReg:registry=https://${REGISTRY_NAME} +//${REGISTRY_NAME}/:_authToken=${AUTH_TOKEN} +``` + +The environment variables will be replaced by the values present in the manifest or from the developer keyrings. diff --git a/fern/docs/pages/references/manifest.mdx b/fern/docs/pages/references/manifest.mdx index 07c7a25d..a1e0ea8c 100644 --- a/fern/docs/pages/references/manifest.mdx +++ b/fern/docs/pages/references/manifest.mdx @@ -1,5 +1,7 @@ -The following section is for version 2 of the manifest specification. For the previous version, see [Manifest V1](/snap-in-development/references/snap-in-v-1-manifest). + The following section is for version 2 of the manifest specification. For the + previous version, see [Manifest + V1](/snap-in-development/references/snap-in-v-1-manifest). The snap-in manifest is what the developers write to define a snap-in. The manifest has the following sections: @@ -57,6 +59,7 @@ keyrings: - snap_in_secret display_name: Your secret token ``` + Keyrings defined in the manifest can be provided in the snap-in configuration screens and are made available to the function. The keyring type is used to determine the type of the keyring and restricts selection on the configuration screen to valid types. Organization keyrings are common to the organization, while user keyrings are set per user. User keyrings are optional, so the developer must correctly handle cases where the keyring isn't found. @@ -679,7 +682,8 @@ inputs: ui: display_name: ``` -Inputs of type `timestamp`, `date` and `array` of `booleans` aren't supported. + +Inputs of type `timestamp`, `date` and `array` of `booleans` aren't supported. ## Tags @@ -706,7 +710,7 @@ commands: - surface: discussions object_types: - conversation - usage_hint: "number of tokens to generate" + usage_hint: 'number of tokens to generate' function: generate_summary ``` @@ -743,3 +747,24 @@ automations: ``` For custom event sources, whatever event key you emit from your policy, the event name will be `custom:`. + +## Build config + +Build configuration is used to pass values during the snap-in build process. The values are present as environment variables. This is useful if the snap-in requires libraries that +are either private or from different npm registry than the default. + +Build config is defined as: + +```yaml +build_config: + environment_variables: + - name: + description: + type: + value: +``` + +`type` can either be `constant` or `keyring`. + +`value` is either the actual value of the environment variable or name of the developer keyring that +contains the secret depending on the type being `constant` or `keyring`. From 44afbd9b90d96960e93ad81b89c6bced2a11518d Mon Sep 17 00:00:00 2001 From: navneel mandal Date: Fri, 26 Apr 2024 22:31:59 +0530 Subject: [PATCH 02/12] update --- fern/docs/pages/references/build_config.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/fern/docs/pages/references/build_config.mdx b/fern/docs/pages/references/build_config.mdx index 4a420a0f..f6a607d2 100644 --- a/fern/docs/pages/references/build_config.mdx +++ b/fern/docs/pages/references/build_config.mdx @@ -46,8 +46,6 @@ developer_keyrings: ## Using the variables defined in config -## Private Registries - If the package is present in private registries, the developer can update the `.npmrc` file in the `code` folder from the template to include the URL of the registry and the token. For example, to use variables defined in manifest defined in the previous section, the `.npmrc` file will look something like this: @@ -57,4 +55,8 @@ For example, to use variables defined in manifest defined in the previous sectio //${REGISTRY_NAME}/:_authToken=${AUTH_TOKEN} ``` -The environment variables will be replaced by the values present in the manifest or from the developer keyrings. +To ensure that the `.npmrc` file is valid and can be used to install the libraries, export the variables defined in the manifest locally with the correct values and install the library + +``` + npm install @githubReg/ +``` From e9def0e5c911d493970c1453e63aa035b4798884 Mon Sep 17 00:00:00 2001 From: Navneel Mandal <34075042+navneel99@users.noreply.github.com> Date: Tue, 30 Apr 2024 12:20:45 +0530 Subject: [PATCH 03/12] Apply suggestions from code review Co-authored-by: Ben Colborn <117322957+bc-devrev@users.noreply.github.com> --- fern/docs/pages/references/build_config.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/fern/docs/pages/references/build_config.mdx b/fern/docs/pages/references/build_config.mdx index f6a607d2..32a2bee2 100644 --- a/fern/docs/pages/references/build_config.mdx +++ b/fern/docs/pages/references/build_config.mdx @@ -1,4 +1,4 @@ -Build config is a way to provide data to the snap-in build process. Currently, the only way to send data +Build config is a way to provide data to the snap-in build process through environment variables. is through environment variables that the build process has access to. This is useful if the developer wants to import libraries from a different registry or wants to use private packages that @@ -17,7 +17,7 @@ build_config: value: ``` -For example, to import a library that use the GitHub NPM registry, we should add +For example, to import a library that uses the GitHub NPM registry, add the following variables to the build config ```yaml @@ -33,7 +33,7 @@ build_config: value: access_token ``` -Since AUTH_TOKEN is a sensitive informantion that should not be hardcoded in the manifest, +Since "AUTH_TOKEN" is sensitive information that should not be hardcoded in the manifest, the developer can instead mention the name of the developer keyring and during snap-in version creation time, provide the developer keyring to take the value from. From 039e1f4d0713e43d91e5105b4ff4fc9061c46f41 Mon Sep 17 00:00:00 2001 From: navneel mandal Date: Tue, 30 Apr 2024 12:38:07 +0530 Subject: [PATCH 04/12] rename page and add to sidebar --- .../pages/references/{build_config.mdx => build-config.mdx} | 3 +-- fern/docs/pages/references/manifest.mdx | 4 +++- fern/versions/public.yml | 3 +++ 3 files changed, 7 insertions(+), 3 deletions(-) rename fern/docs/pages/references/{build_config.mdx => build-config.mdx} (92%) diff --git a/fern/docs/pages/references/build_config.mdx b/fern/docs/pages/references/build-config.mdx similarity index 92% rename from fern/docs/pages/references/build_config.mdx rename to fern/docs/pages/references/build-config.mdx index 32a2bee2..a5c8e1e7 100644 --- a/fern/docs/pages/references/build_config.mdx +++ b/fern/docs/pages/references/build-config.mdx @@ -1,5 +1,4 @@ -Build config is a way to provide data to the snap-in build process through environment variables. -is through environment variables that the build process has access to. +Build configuration is used to configure the build process of the Snap-in. For e.g. It can be used to set the environment variables used during the build process. This is useful if the developer wants to import libraries from a different registry or wants to use private packages that require authentication token. diff --git a/fern/docs/pages/references/manifest.mdx b/fern/docs/pages/references/manifest.mdx index a1e0ea8c..b45cf1c0 100644 --- a/fern/docs/pages/references/manifest.mdx +++ b/fern/docs/pages/references/manifest.mdx @@ -750,7 +750,7 @@ For custom event sources, whatever event key you emit from your policy, the even ## Build config -Build configuration is used to pass values during the snap-in build process. The values are present as environment variables. This is useful if the snap-in requires libraries that +uild configuration is used to configure the build process of the Snap-In. For e.g. It can be used to set the environment variables used during the build process. This is useful if the snap-in requires libraries that are either private or from different npm registry than the default. Build config is defined as: @@ -768,3 +768,5 @@ build_config: `value` is either the actual value of the environment variable or name of the developer keyring that contains the secret depending on the type being `constant` or `keyring`. + +For further information, see [Build Config](/snap-in-development/references/build-config.mdx). diff --git a/fern/versions/public.yml b/fern/versions/public.yml index ebde4db4..c9a1968b 100644 --- a/fern/versions/public.yml +++ b/fern/versions/public.yml @@ -150,6 +150,9 @@ navigation: - page: Snap-in resources slug: snap-in-resources path: ../docs/pages/references/snap-in-resources.mdx + - page: Build Config + slug: build-config + path: ../docs/pages/references/build-config.mdx - page: Development best practices slug: best-practices path: ../docs/pages/best_practices.mdx From f6637621823e047979603606841dac8f007661c3 Mon Sep 17 00:00:00 2001 From: navneel mandal Date: Tue, 30 Apr 2024 12:43:08 +0530 Subject: [PATCH 05/12] update links --- fern/docs/pages/references/manifest.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/docs/pages/references/manifest.mdx b/fern/docs/pages/references/manifest.mdx index b45cf1c0..ed9819a9 100644 --- a/fern/docs/pages/references/manifest.mdx +++ b/fern/docs/pages/references/manifest.mdx @@ -64,7 +64,7 @@ Keyrings defined in the manifest can be provided in the snap-in configuration sc Organization keyrings are common to the organization, while user keyrings are set per user. User keyrings are optional, so the developer must correctly handle cases where the keyring isn't found. -To view the supported connection types, see [Keyrings](/snap-in-development/references/keyrings). +To view the supported connection types, see [Keyrings](/references/keyrings). ## Developer keyrings @@ -769,4 +769,4 @@ build_config: `value` is either the actual value of the environment variable or name of the developer keyring that contains the secret depending on the type being `constant` or `keyring`. -For further information, see [Build Config](/snap-in-development/references/build-config.mdx). +For further information, see [Build Config](/references/build-config.mdx). From 003703e7c63445d533f02d65bb02bbceaf07c434 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Tue, 30 Apr 2024 12:55:43 +0530 Subject: [PATCH 06/12] fix link --- fern/docs/pages/references/manifest.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/docs/pages/references/manifest.mdx b/fern/docs/pages/references/manifest.mdx index ed9819a9..78ba3d1a 100644 --- a/fern/docs/pages/references/manifest.mdx +++ b/fern/docs/pages/references/manifest.mdx @@ -769,4 +769,4 @@ build_config: `value` is either the actual value of the environment variable or name of the developer keyring that contains the secret depending on the type being `constant` or `keyring`. -For further information, see [Build Config](/references/build-config.mdx). +For further information, see [Build Config](/references/build-config). From e41010fa42169d4601e2befaa944fcae13dd5997 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Tue, 30 Apr 2024 13:02:03 +0530 Subject: [PATCH 07/12] Update build-config.mdx --- fern/docs/pages/references/build-config.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/fern/docs/pages/references/build-config.mdx b/fern/docs/pages/references/build-config.mdx index a5c8e1e7..eec0c4ac 100644 --- a/fern/docs/pages/references/build-config.mdx +++ b/fern/docs/pages/references/build-config.mdx @@ -1,7 +1,7 @@ -Build configuration is used to configure the build process of the Snap-in. For e.g. It can be used to set the environment variables used during the build process. +The build configuration is used to configure the build process of the snap-in. For example, it can be used to set the environment variables used during the build process. This is useful if the developer wants to import libraries from a different registry or wants to use private packages that -require authentication token. +requires an authentication token. ## Specifying the Config @@ -23,7 +23,7 @@ the following variables to the build config build_config: environment_variables: - name: REGISTRY_NAME - description: Name of the github registry to import the library. + description: Name of the GitHub registry to import the library. type: constant value: npm.pkg.github.com - name: AUTH_TOKEN @@ -47,7 +47,7 @@ developer_keyrings: If the package is present in private registries, the developer can update the `.npmrc` file in the `code` folder from the template to include the URL of the registry and the token. -For example, to use variables defined in manifest defined in the previous section, the `.npmrc` file will look something like this: +For example, to use variables defined in the manifest defined in the previous section, the `.npmrc` file will look something like this: ```.npmrc @githubReg:registry=https://${REGISTRY_NAME} From 71fda0aef9c4141772eb904da789dad10adb58b4 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Tue, 30 Apr 2024 13:06:10 +0530 Subject: [PATCH 08/12] Update manifest.mdx --- fern/docs/pages/references/manifest.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/docs/pages/references/manifest.mdx b/fern/docs/pages/references/manifest.mdx index 78ba3d1a..5ab5efae 100644 --- a/fern/docs/pages/references/manifest.mdx +++ b/fern/docs/pages/references/manifest.mdx @@ -750,7 +750,7 @@ For custom event sources, whatever event key you emit from your policy, the even ## Build config -uild configuration is used to configure the build process of the Snap-In. For e.g. It can be used to set the environment variables used during the build process. This is useful if the snap-in requires libraries that +The build configuration is used to configure the build process of the snap-In. For example, it can be used to set the environment variables used during the build process. This is useful if the snap-in requires libraries that are either private or from different npm registry than the default. Build config is defined as: From e11030036d43f33386e172a48642607fb08b0fcf Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Tue, 30 Apr 2024 13:11:12 +0530 Subject: [PATCH 09/12] Update manifest.mdx --- fern/docs/pages/references/manifest.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/fern/docs/pages/references/manifest.mdx b/fern/docs/pages/references/manifest.mdx index 5ab5efae..839c50b5 100644 --- a/fern/docs/pages/references/manifest.mdx +++ b/fern/docs/pages/references/manifest.mdx @@ -16,7 +16,7 @@ version: 2 ## Keyrings -Keyrings are secret tokens used to make calls to external systems. They can be categorized either as organization scoped or user scoped. Keyrings are specified in the manifest with the following syntax: +Keyrings are secret tokens used to make calls to external systems. They can be categorized either as organization-scoped or user-scoped. Keyrings are specified in the manifest with the following syntax: ```yaml keyrings: @@ -657,7 +657,7 @@ event_sources: ## Inputs -Inputs are implemented using per-object schemas, which is a customization technique to store custom schemas inline with the object. Each input's schema maps to a FieldDescriptor. Inputs, like keyrings and event sources, are organization and user scoped. Organization-scoped inputs are set by the admins of the organization and are common across all users. User inputs are set individually. +Inputs are implemented using per-object schemas, which is a customization technique to store custom schemas in line with the object. Each input's schema maps to a FieldDescriptor. Inputs, like keyrings and event sources, are organization and user-scoped. Organization-scoped inputs are set by the admins of the organization and are common across all users. User inputs are set individually. Inputs are defined as: @@ -683,7 +683,7 @@ inputs: display_name: ``` -Inputs of type `timestamp`, `date` and `array` of `booleans` aren't supported. +Inputs of type `timestamp`, `date`, and `array` of `booleans` aren't supported. ## Tags @@ -694,7 +694,7 @@ For example: ```yaml tags: - name: github.branch.name - description: Tag storing github branch name. + description: Tag storing GitHub branch name. ``` ## Commands @@ -750,8 +750,8 @@ For custom event sources, whatever event key you emit from your policy, the even ## Build config -The build configuration is used to configure the build process of the snap-In. For example, it can be used to set the environment variables used during the build process. This is useful if the snap-in requires libraries that -are either private or from different npm registry than the default. +The build configuration is used to configure the build process of the snap-in. For example, it can be used to set the environment variables used during the build process. This is useful if the snap-in requires libraries that +are either private or from a different npm registry than the default. Build config is defined as: From 99511f9c0d4afa07c073dcc57c0bc380ca10d345 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Thu, 2 May 2024 12:14:58 +0530 Subject: [PATCH 10/12] Update fern/docs/pages/references/manifest.mdx Co-authored-by: Ben Colborn <117322957+bc-devrev@users.noreply.github.com> --- fern/docs/pages/references/manifest.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/docs/pages/references/manifest.mdx b/fern/docs/pages/references/manifest.mdx index 839c50b5..b193c003 100644 --- a/fern/docs/pages/references/manifest.mdx +++ b/fern/docs/pages/references/manifest.mdx @@ -657,7 +657,7 @@ event_sources: ## Inputs -Inputs are implemented using per-object schemas, which is a customization technique to store custom schemas in line with the object. Each input's schema maps to a FieldDescriptor. Inputs, like keyrings and event sources, are organization and user-scoped. Organization-scoped inputs are set by the admins of the organization and are common across all users. User inputs are set individually. +Inputs are implemented using per-object schemas, which is a customization technique to store custom schemas in line with the object. Each input's schema maps to a `FieldDescriptor`. Inputs, like keyrings and event sources, are organization and user-scoped. Organization-scoped inputs are set by the admins of the organization and are common across all users. User inputs are set individually. Inputs are defined as: From 75af020f2c510913fda8d01d2f443b2562e01014 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Thu, 2 May 2024 12:15:08 +0530 Subject: [PATCH 11/12] Update fern/docs/pages/references/build-config.mdx Co-authored-by: Ben Colborn <117322957+bc-devrev@users.noreply.github.com> --- fern/docs/pages/references/build-config.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/docs/pages/references/build-config.mdx b/fern/docs/pages/references/build-config.mdx index eec0c4ac..8207f6c0 100644 --- a/fern/docs/pages/references/build-config.mdx +++ b/fern/docs/pages/references/build-config.mdx @@ -1,7 +1,7 @@ The build configuration is used to configure the build process of the snap-in. For example, it can be used to set the environment variables used during the build process. This is useful if the developer wants to import libraries from a different registry or wants to use private packages that -requires an authentication token. +require an authentication token. ## Specifying the Config From 7f0a08b130d0cf1b80e65bc10a6a9b8325069ed4 Mon Sep 17 00:00:00 2001 From: Karuna Tata Date: Wed, 8 May 2024 14:13:40 +0530 Subject: [PATCH 12/12] Update build-config.mdx --- fern/docs/pages/references/build-config.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/fern/docs/pages/references/build-config.mdx b/fern/docs/pages/references/build-config.mdx index 8207f6c0..73529901 100644 --- a/fern/docs/pages/references/build-config.mdx +++ b/fern/docs/pages/references/build-config.mdx @@ -3,7 +3,7 @@ The build configuration is used to configure the build process of the snap-in. F This is useful if the developer wants to import libraries from a different registry or wants to use private packages that require an authentication token. -## Specifying the Config +## Specifying the config Build config is defined as: @@ -17,7 +17,7 @@ build_config: ``` For example, to import a library that uses the GitHub NPM registry, add -the following variables to the build config +the following variables to the build config: ```yaml build_config: @@ -33,7 +33,7 @@ build_config: ``` Since "AUTH_TOKEN" is sensitive information that should not be hardcoded in the manifest, -the developer can instead mention the name of the developer keyring and during snap-in version creation +the developer can instead mention the name of the developer keyring and, during snap-in version creation time, provide the developer keyring to take the value from. ```yaml