From 19b9052c14ea5e59cc23e753ab3112c73a489bae Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Mon, 30 Sep 2024 13:47:10 +0100 Subject: [PATCH 1/4] feat(cloud): add environment configuration guide --- cloud/features/approval-workflows.mdx | 3 +- cloud/guides/configuring-environments.mdx | 151 ++++++++++++++++++++++ mint.json | 3 +- 3 files changed, 155 insertions(+), 2 deletions(-) create mode 100644 cloud/guides/configuring-environments.mdx diff --git a/cloud/features/approval-workflows.mdx b/cloud/features/approval-workflows.mdx index f454a28..366a74c 100644 --- a/cloud/features/approval-workflows.mdx +++ b/cloud/features/approval-workflows.mdx @@ -81,7 +81,8 @@ Once the pull request is merged, the changes will be deployed to the protected e You can leverage GitHub's existing [Code Owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) feature to automatically request reviews from specific teams or individuals - when a proposal is created. This is a great way to automate requesting the relevant teams and individuals for their approval input. + when a proposal is created. This is a great way to automate requesting the + relevant teams and individuals for their approval input. ## Evaluation diff --git a/cloud/guides/configuring-environments.mdx b/cloud/guides/configuring-environments.mdx new file mode 100644 index 0000000..1f4d8bd --- /dev/null +++ b/cloud/guides/configuring-environments.mdx @@ -0,0 +1,151 @@ +--- +title: Configuring Environments +description: Learn how to configure different aspects of your Flipt environments +--- + +## Commit Messages, Pull-Request Titles and Bodies + +Flipt Cloud dynamically generates commit messages and pull-requests based on parameters of the changes being made. +It passes these parameters through Go templates to produce the resulting messages. +We have configured some sensible defaults, however, these can be overridden on a per Flipt environment basis. + +In order to override these templates, a `flipt.yaml` file is provided at the root of your environment tree. + +```filetree +. +└─ production +    └─ flipt.yaml +``` + + + To recap: an environment is a combination of a Git `repository`, a `branch` + name and `directory` path. These are selected when you create your environment + in Flipt Cloud. The `flipt.yaml` must exist in this directory and branch in + order to configure the relevant environment. + + +When this file is not provided, a default one is implicitly generated. The default is effectively the following: + +```yaml +version: "1.0" +templates: + commit_message: |- + {{- if eq (len .Changes) 1 }} + {{- (index .Changes 0) }} + {{- else -}} + updated multiple resources + {{ range $change := .Changes }} + {{ $change }} + {{- end }} + {{- end }} + proposal_title: "Flipt: Update features in {{ .Base.Name }}" + proposal_body: |- + Update Flipt resources in [{{ .Base.Name }}]({{ .Base.HostURL }}) + The branched environment can be viewed at [{{ .Branch.Name }}]({{ .Branch.HostURL }}) +``` + +### Commit Message + +Commit message templates are supplied with a list of changes. +Currently, Flipt only provides a single change. +However, we have assumed this can change in the future and so we provide a list of changes. +A change is a combination of a `verb` and `resource`. +A resource is a combination of `type`, `namespace` (when relevant) and `key`. + +The following is a pseudo-schema for the context passed to this template: + +```go Context +{ + Changes: []Change{ + { + Verb: string // e.g. create, update or delete + Resource: { + Type: { + Package: string // e.g. flipt.core + Name: string // e.g. Flag + } + Namespace: string // e.g. default + Key: string // e.g. my-flag-key + } + } + } +} +``` + +Simply printing out a change in the template (e.g. `{{ (index .Changes 0) }}`) results in the following format: + +``` + [/] +``` + + +The following gives an example of how you could change the above template to produce semantic commits: + +```yaml +version: "1.0" +templates: + commit_message: |- + {{- if eq (len .Changes) 1 }} + {{- printf "feat(flipt/%s): %s" .Environment.Name (index .Changes 0) }} + {{- else -}} + updated multiple resources + {{ range $change := .Changes }} + {{- printf "feat(flipt/%s): %s" .Environment.Name $change }} + {{- end }} + {{- end }} +``` + + + +### Proposal (Pull-Request) Title and Body + +Proposals (generated Pull-Requests) have a configurable title and body templates. +Both templates are provided with the `base` environment and the `branch` environment configuration. + +The following is a pseudo-schema for the context passed to these templates: + +```go Context +{ + Base: { + Name: string // e.g. production + Organization: string // e.g. myorg + Host: string // e.g. production-myorg.flipt.cloud + Branch: string // e.g. main + Directory: string // e.g. production + } + Branch: { + Name: string // e.g. interestingcohen + Organization: string // e.g. myorg + Host: string // e.g. interestingcohen-production-myorg.flipt.cloud + Branch: string // e.g. flipt/production/interestingcohen + Directory: string // e.g. production + } +} +``` + + + +The following gives an example of how you could change the above template to produce semantic commits: + +```yaml +version: "1.0" +templates: + proposal_title: "feat: update feature flags in {{ .Base.Name }}" +``` + + + +The following gives an example of how you could change the above template to produce semantic commits: + +```yaml +version: "1.0" +templates: + proposal_body: |- + Update Flipt resources for the {{ .Base.Organization }} in [{{ .Base.Name }}]({{ .Base.HostURL }}). + The branched environment can be viewed at [{{ .Branch.Name }}]({{ .Branch.HostURL }}). +``` + + + + +### Proposal (Pull-Request) Bodies diff --git a/mint.json b/mint.json index c7247f7..bb78f78 100644 --- a/mint.json +++ b/mint.json @@ -273,7 +273,8 @@ "group": "Guides", "pages": [ "cloud/guides/getting-started", - "cloud/guides/production" + "cloud/guides/production", + "cloud/guides/configuring-environments" ] }, { From 872876b95082e6b4a38f9754b9662aa10b41f9f1 Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Mon, 30 Sep 2024 14:06:04 +0100 Subject: [PATCH 2/4] chore(cloud/guides): update configuring environments based on linter output --- .eslintignore | 3 ++- .vale.ini | 3 ++- cloud/guides/configuring-environments.mdx | 20 +++++++++----------- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.eslintignore b/.eslintignore index 45ed0b4..8ed3063 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1 +1,2 @@ -cloud/overview.mdx \ No newline at end of file +cloud/overview.mdx +cloud/guides/configuring-environments.mdx diff --git a/.vale.ini b/.vale.ini index 06dfaa3..d8d00b1 100644 --- a/.vale.ini +++ b/.vale.ini @@ -24,4 +24,5 @@ Openly.A11Y = warning Openly.Punctuation = warning Openly.Spelling = disabled Openly.So = warning -Openly.ThereIs = warning \ No newline at end of file +Openly.ThereIs = warning +Openly.Titles = disabled diff --git a/cloud/guides/configuring-environments.mdx b/cloud/guides/configuring-environments.mdx index 1f4d8bd..1cabb63 100644 --- a/cloud/guides/configuring-environments.mdx +++ b/cloud/guides/configuring-environments.mdx @@ -7,11 +7,11 @@ description: Learn how to configure different aspects of your Flipt environments Flipt Cloud dynamically generates commit messages and pull-requests based on parameters of the changes being made. It passes these parameters through Go templates to produce the resulting messages. -We have configured some sensible defaults, however, these can be overridden on a per Flipt environment basis. +While cloud is configured some sensible defaults, these can be overridden on a per Flipt environment basis. -In order to override these templates, a `flipt.yaml` file is provided at the root of your environment tree. +To override these templates you must provide a `flipt.yaml` file at the root of your environment tree. -```filetree +```console . └─ production    └─ flipt.yaml @@ -24,7 +24,7 @@ In order to override these templates, a `flipt.yaml` file is provided at the roo order to configure the relevant environment. -When this file is not provided, a default one is implicitly generated. The default is effectively the following: +When this file isn't provided, a default one is implicitly generated. The default is effectively the following: ```yaml version: "1.0" @@ -48,7 +48,7 @@ templates: Commit message templates are supplied with a list of changes. Currently, Flipt only provides a single change. -However, we have assumed this can change in the future and so we provide a list of changes. +However, this may change in the future. As such, the template is provided a list of changes. A change is a combination of a `verb` and `resource`. A resource is a combination of `type`, `namespace` (when relevant) and `key`. @@ -72,14 +72,14 @@ The following is a pseudo-schema for the context passed to this template: } ``` -Simply printing out a change in the template (e.g. `{{ (index .Changes 0) }}`) results in the following format: +Simply printing out a change in the template (for example,`{{ (index .Changes 0) }}`) results in the following format: ``` [/] ``` -The following gives an example of how you could change the above template to produce semantic commits: +The following gives an example of how to change the above template to produce semantic commits: ```yaml version: "1.0" @@ -125,7 +125,7 @@ The following is a pseudo-schema for the context passed to these templates: -The following gives an example of how you could change the above template to produce semantic commits: +The following gives an example of how to change the above template to produce semantic commits: ```yaml version: "1.0" @@ -135,7 +135,7 @@ templates: -The following gives an example of how you could change the above template to produce semantic commits: +The following gives an example of how to change the above template to produce semantic commits: ```yaml version: "1.0" @@ -147,5 +147,3 @@ templates: - -### Proposal (Pull-Request) Bodies From 28ff571224b30073bff37773be12564d92f5f9a9 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Mon, 30 Sep 2024 18:47:17 -0400 Subject: [PATCH 3/4] chore: rm beta re cloud, couple fixups Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com> --- cloud/benefits.mdx | 7 ++----- cloud/concepts.mdx | 7 ++----- cloud/guides/configuring-environments.mdx | 22 +++++++++++++--------- cloud/guides/getting-started.mdx | 7 ++----- cloud/guides/production.mdx | 4 ---- 5 files changed, 19 insertions(+), 28 deletions(-) diff --git a/cloud/benefits.mdx b/cloud/benefits.mdx index 9c64f2f..27436d0 100644 --- a/cloud/benefits.mdx +++ b/cloud/benefits.mdx @@ -5,11 +5,8 @@ mode: "wide" --- - Flipt Cloud is currently in beta. Some functionality may be subject to - change. - -Ready to try Flipt Cloud? [Sign up here](https://flipt.cloud) for a 14-day free trial. - + Ready to try Flipt Cloud? [Sign up here](https://flipt.cloud) for a 14-day + free trial. At Flipt, we aim to provide our users with the best possible feature flagging experience. That's why we're excited to introduce Flipt Cloud, a new offering that combines the best of both worlds: the simplicity and flexibility of a cloud service with the scalability and reliability of self-hosted Flipt. diff --git a/cloud/concepts.mdx b/cloud/concepts.mdx index 39c2a5d..9f60ac9 100644 --- a/cloud/concepts.mdx +++ b/cloud/concepts.mdx @@ -4,11 +4,8 @@ description: This document describes the basic concepts of Flipt Cloud. --- - Flipt Cloud is currently in beta. Some functionality may be subject to - change. - -Ready to try Flipt Cloud? [Sign up here](https://flipt.cloud) for a 14-day free trial. - + Ready to try Flipt Cloud? [Sign up here](https://flipt.cloud) for a 14-day + free trial. Flipt Cloud is a fully solution where we host and operate Flipt for you. You no longer need to deploy or manage Flipt instances yourself. We provide a secure, scalable, and feature-rich environment with enterprise-grade authentication and authorization built-in. diff --git a/cloud/guides/configuring-environments.mdx b/cloud/guides/configuring-environments.mdx index 1cabb63..89549d5 100644 --- a/cloud/guides/configuring-environments.mdx +++ b/cloud/guides/configuring-environments.mdx @@ -6,8 +6,8 @@ description: Learn how to configure different aspects of your Flipt environments ## Commit Messages, Pull-Request Titles and Bodies Flipt Cloud dynamically generates commit messages and pull-requests based on parameters of the changes being made. -It passes these parameters through Go templates to produce the resulting messages. -While cloud is configured some sensible defaults, these can be overridden on a per Flipt environment basis. +It passes these parameters through [Go templates](https://pkg.go.dev/text/template) to produce the resulting messages. +While cloud is configured with some sensible defaults, these can be overridden on a per Flipt environment basis. To override these templates you must provide a `flipt.yaml` file at the root of your environment tree. @@ -18,10 +18,14 @@ To override these templates you must provide a `flipt.yaml` file at the root of ``` - To recap: an environment is a combination of a Git `repository`, a `branch` - name and `directory` path. These are selected when you create your environment - in Flipt Cloud. The `flipt.yaml` must exist in this directory and branch in - order to configure the relevant environment. + + An environment is a combination of a Git `repository`, a `branch` name and + `directory` path. These are selected when you create your environment in Flipt + Cloud. + + The `flipt.yaml` file must exist in this directory and branch in order + to configure the relevant environment. + When this file isn't provided, a default one is implicitly generated. The default is effectively the following: @@ -78,7 +82,7 @@ Simply printing out a change in the template (for example,`{{ (index .Changes 0) [/] ``` - + The following gives an example of how to change the above template to produce semantic commits: ```yaml @@ -124,7 +128,7 @@ The following is a pseudo-schema for the context passed to these templates: ``` - + The following gives an example of how to change the above template to produce semantic commits: ```yaml @@ -134,7 +138,7 @@ templates: ``` - + The following gives an example of how to change the above template to produce semantic commits: ```yaml diff --git a/cloud/guides/getting-started.mdx b/cloud/guides/getting-started.mdx index 047d713..f80b160 100644 --- a/cloud/guides/getting-started.mdx +++ b/cloud/guides/getting-started.mdx @@ -4,11 +4,8 @@ description: Learn how to get started with Flipt Cloud --- - Flipt Cloud is currently in beta. Some functionality may be subject to - change. - -Ready to try Flipt Cloud? [Sign up here](https://flipt.cloud) for a 14-day free trial. - + Ready to try Flipt Cloud? [Sign up here](https://flipt.cloud) for a 14-day + free trial. ## Prerequisites diff --git a/cloud/guides/production.mdx b/cloud/guides/production.mdx index 626b0c7..f02dc2c 100644 --- a/cloud/guides/production.mdx +++ b/cloud/guides/production.mdx @@ -4,11 +4,7 @@ description: Learn how to scale your feature flagging operations with Flipt Clou --- - Flipt Cloud is currently in beta. Some functionality may be subject to - change. - Ready to try Flipt Cloud? [Sign up here](https://flipt.cloud) for a 14-day free trial. - ## Prerequisites From 9432007fba97f1adda9b119872e1a38a7bd82cad Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Mon, 30 Sep 2024 18:50:58 -0400 Subject: [PATCH 4/4] chore: fmt Signed-off-by: Mark Phelps <209477+markphelps@users.noreply.github.com> --- cloud/guides/configuring-environments.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cloud/guides/configuring-environments.mdx b/cloud/guides/configuring-environments.mdx index ae4ec68..4280e7f 100644 --- a/cloud/guides/configuring-environments.mdx +++ b/cloud/guides/configuring-environments.mdx @@ -19,12 +19,12 @@ To override these templates you must provide a `flipt.yaml` file at the root of - An environment is a combination of a Git `repository`, a `branch` name and - `directory` path. These are selected when you create your environment in Flipt - Cloud. +An environment is a combination of a Git `repository`, a `branch` name and +`directory` path. These are selected when you create your environment in Flipt +Cloud. - The `flipt.yaml` file must exist in this directory and branch in order - to configure the relevant environment. +The `flipt.yaml` file must exist in this directory and branch in order +to configure the relevant environment.