Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(cli/validate): add documentation around --extra-schema #173

Merged
merged 6 commits into from
Jan 23, 2024
Merged

feat(cli/validate): add documentation around --extra-schema #173

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1852d41
feat(cli/validate): add documentation around --extra-schema
GeorgeMac Jan 19, 2024
2988fc9
chore: format code
GeorgeMac Jan 19, 2024
f17fa6a
chore(cli/validate): fix spelling mistakes
GeorgeMac Jan 19, 2024
05d330c
Merge branch 'gm/flipt-validate-extra-schema' of github.com:flipt-io/…
GeorgeMac Jan 19, 2024
7d6b5e0
chore: Update cli/commands/validate.mdx
markphelps Jan 23, 2024
0ac70ee
chore: add link to cue
markphelps Jan 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions cli/commands/validate.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,66 @@
### Options

```
-e, --extra-schema string path to extra schema constraints
-F, --format string output format: json, text (default "text")
-h, --help help for validate
--issue-exit-code int Exit code to use when issues are found (default 1)
```

### Behavior

This command validates Flipt's declarative feature configuration files.

It looks for features flag definitions in the same way as Flipt's declarative backends. Checkout the documentation on [locating flag state](/configuration/storage#locating-flag-state) to learn more about this process.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should introduce Cue here by puting something here about how it uses Cue under the hood, and link to the Cue project?

### Extra Schema

Check warning on line 25 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.Titles] 'Extra Schema' should be in sentence case

Raw Output:
{"message": "[Openly.Titles] 'Extra Schema' should be in sentence case", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 25, "column": 5}}}, "severity": "WARNING"}

The flag `--extra-schema` (short form `-e`) can be used to pass additional constraints via a [CUE](https://cuelang.org/) schema file.
This file will be unified with the base schema used within `flipt validate` to ensure the format of Flipt files.

Check warning on line 28 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 28, "column": 11}}}, "severity": "WARNING"}
You can find the base schema [here](https://github.com/flipt-io/flipt/blob/main/internal/cue/flipt.cue).

As an example, take the following flipt `features.yaml` file:

```yaml
flags:
- key: someFeature
name: Some Feature
```

Running validate will succeed when provided with a path to this file.

Check warning on line 39 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 39, "column": 18}}}, "severity": "WARNING"}

```console
➜ flipt validate
➜ echo $?
0
```

By default, the flag `description` field is not required. However, imagine that you want to ensure this field is always provided with a non-empty string. You can do this via the `--extra-schema` flag and a CUE definition.

Check failure on line 47 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'isn't' instead of 'is not'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 47, "column": 42}}}, "severity": "ERROR"}
In this instance we're going to create a CUE file named `extended.cue`.

Check warning on line 48 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'we'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'we'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 48, "column": 18}}}, "severity": "WARNING"}
Within this file we will add a constraint to the `#Flag` CUE definition, which ensures our desired behavior.

Check warning on line 49 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 49, "column": 21}}}, "severity": "WARNING"}

Check warning on line 49 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'our'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'our'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 49, "column": 88}}}, "severity": "WARNING"}

```cue
#Flag: {
description: =~"^.+$"
}
```

This definition ensures that description is both supplied and that the value matches the regular expression.
The regular expression in this example ensures a string with a length of at least 1 character.

Now when invoking the validate sub-command, we pass the path to this extra CUE definition:

Check warning on line 60 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'we'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'we'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 60, "column": 45}}}, "severity": "WARNING"}

```console
➜ flipt validate -e extended.cue
Validation failed!

- Message : flags.0.description: incomplete value =~"^.+$"
File : features.yaml
Line : 2
```

Here we see that our additional constraint on description is being validated and described in the output.

Check warning on line 71 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'we'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'we'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 71, "column": 6}}}, "severity": "WARNING"}

Check warning on line 71 in cli/commands/validate.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'our'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'our'.", "location": {"path": "cli/commands/validate.mdx", "range": {"start": {"line": 71, "column": 18}}}, "severity": "WARNING"}

### More Info

See the [flag state](/configuration/storage#flag-state-configuration) section of the documentation for more information.
Loading