diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 00000000..f6f40344 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,30 @@ +# OpenFeature CLI Design + +This document describes the design considerations and goals for the OpenFeature CLI tool. + +## Why Code Generation? + +Code generation automates the creation of strongly typed flag accessors, minimizing configuration errors and providing a better developer experience. +By generating these accessors, developers can avoid issues related to incorrect flag names or types, resulting in more reliable and maintainable code. + +Benefits of the code generation approach: + +- **Type Safety**: Catch flag-related errors at compile time instead of runtime +- **IDE Support**: Get autocomplete and documentation for your flags +- **Refactoring Support**: Rename flags and the changes propagate throughout your codebase +- **Discoverability**: Make it easier for developers to find and use available flags + +## Goals + +- **Unified Flag Manifest Format**: Establish a standardized flag manifest format that can be easily converted from existing configurations. +- **Strongly Typed Flag Accessors**: Develop a CLI tool to generate strongly typed flag accessors for multiple programming languages. +- **Modular and Extensible Design**: Create a format that allows for future extensions and modularization of flags. +- **Language Agnostic**: Support multiple programming languages through a common flag manifest format. +- **Provider Independence**: Work with any feature flag provider that can be adapted to the OpenFeature API. + +## Non-Goals + +- **Full Provider Integration**: The initial scope does not include creating tools to convert provider-specific configurations to the new flag manifest format. +- **Validation of Flag Configs**: The project will not initially focus on validating flag configurations for consistency with the flag manifest. +- **General-Purpose Configuration**: The project will not aim to create a general-purpose configuration tool for feature flags beyond the scope of the code generation tool. +- **Runtime Flag Management**: The CLI is not intended to replace provider SDKs for runtime flag evaluation. diff --git a/README.md b/README.md index 91c643a0..6bddbf53 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@

- work-in-progress + work-in-progress Slack @@ -30,42 +30,216 @@ ## Overview The OpenFeature CLI is a command-line tool designed to improve the developer experience when working with feature flags. -Currently, features are focused primarily on supporting code generation. +It helps developers manage feature flags consistently across different environments and programming languages by providing powerful utilities for code generation, flag validation, and more. ## Installation -Download packaged binaries from the [releases page](https://github.com/open-feature/codegen/releases). +### via curl -### Why Code Generation? +The OpenFeature CLI can be installed using a shell command. +This method is suitable for most Unix-like operating systems. -Code generation automates the creation of strongly typed flag accessors, minimizing configuration errors and providing a better developer experience. -By generating these accessors, developers can avoid issues related to incorrect flag names or types, resulting in more reliable and maintainable code. +```bash +curl -fsSL https://openfeature.dev/scripts/install_cli.sh | sh +``` -### Goals +### via Docker -- **Unified Flag Manifest Format**: Establish a standardized flag manifest format that can be easily converted from existing configurations. -- **Strongly Typed Flag Accessors**: Develop a CLI tool to generate strongly typed flag accessors for multiple programming languages. -- **Modular and Extensible Design**: Create a format that allows for future extensions and modularization of flags. +The OpenFeature CLI is available as a Docker image in the [GitHub Container Registry](https://github.com/open-feature/cli/pkgs/container/cli). -### Non-Goals +You can run the CLI in a Docker container using the following command: -- **Full Provider Integration**: The initial scope does not include creating tools to convert provider-specific configurations to the new flag manifest format. -- **Validation of Flag Configs**: The project will not initially focus on validating flag configurations for consistency with the flag manifest. -- **General-Purpose Configuration**: The project will not aim to create a general-purpose configuration tool for feature flags beyond the scope of the code generation tool. +```bash +docker run -it -v $(pwd):/local -w /local ghcr.io/open-feature/cli:latest +``` -## Support the project +### via Go -- Give this repo a ⭐️! -- Follow us on social media: +If you have `Go >= 1.23` installed, you can install the CLI using the following command: + +```bash +go install github.com/open-feature/cli@latest +``` + +### via pre-built binaries + +Download the appropriate pre-built binary from the [releases page](https://github.com/open-feature/cli/releases). + +## Quick Start + +1. Create a flag manifest file in your project root: + +```bash +cat > flags.json << EOL +{ + "$schema": "https://raw.githubusercontent.com/open-feature/cli/refs/heads/main/schema/v0/flag-manifest.json", + "flags": { + "enableMagicButton": { + "flagType": "boolean", + "defaultValue": false, + "description": "Activates a special button that enhances user interaction with magical, intuitive functionalities." + } + } +} +EOL +``` + +> [!NOTE] +> This is for demonstration purposes only. +> In a real-world scenario, you would typically want to fetch this file from a remote flag management service. +> See [here](https://github.com/open-feature/cli/issues/3), more more details. + +2. Generate code for your preferred language: + +```bash +openfeature generate react +``` + +See [here](./docs/commands/openfeature_generate.md) for all available options. + +3. View the generated code: + +```bash +cat openfeature.ts +``` + +**Congratulations!** +You have successfully generated your first strongly typed flag accessors. +You can now use the generated code in your application to access the feature flags. +This is just scratching the surface of what the OpenFeature CLI can do. +For more advanced usage, read on! + +## Commands + +The OpenFeature CLI provides the following commands: + +### `init` + +Initialize a new flag manifest in your project. + +```bash +openfeature init +``` + +See [here](./docs/commands/openfeature_init.md), for all available options. + +### `generate` + +Generate strongly typed flag accessors for your project. + +```bash +# Available languages +openfeature generate + +# Basic usage +openfeature generate [language] + +# With custom output directory +openfeature generate typescript --output ./src/flags +``` + +See [here](./docs/commands/openfeature_generate.md), for all available options. + +### `version` + +Print the version number of the OpenFeature CLI. + +```bash +openfeature version +``` + +See [here](./docs/commands/openfeature_version.md), for all available options. + +## Flag Manifest + +The flag manifest is a JSON file that defines your feature flags and their properties. +It serves as the source of truth for your feature flags and is used by the CLI to generate strongly typed accessors. +The manifest file should be named `flags.json` and placed in the root of your project. + +### Flag Manifest Structure + +The flag manifest file should follow the JSON schema defined [here](https://raw.githubusercontent.com/open-feature/cli/refs/heads/main/schema/v0/flag-manifest.json). + +The schema defines the following properties: + +- `$schema`: The URL of the JSON schema for validation. +- `flags`: An object containing the feature flags. + - `flagKey`: A unique key for the flag. + - `description`: A description of what the flag does. + - `type`: The type of the flag (e.g., `boolean`, `string`, `number`, `object`). + - `defaultValue`: The default value of the flag. + +### Example Flag Manifest + +```json +{ + "$schema": "https://raw.githubusercontent.com/open-feature/cli/refs/heads/main/schema/v0/flag-manifest.json", + "flags": { + "uniqueFlagKey": { + "description": "Description of what this flag does", + "type": "boolean|string|number|object", + "defaultValue": "default-value", + } + } +} +``` + +## Configuration + +The OpenFeature CLI uses an optional configuration file to override default settings and customize the behavior of the CLI. +This file can be in JSON or YAML format and should be named either `.openfeature.json` or `.openfeature.yaml`. + +### Configuration File Structure + +```yaml +# Example .openfeature.yaml +manifest: "flags/manifest.json" # Overrides the default manifest path +generate: + output: "src/flags" # Overrides the default output directory + # Any language-specific options can be specified here + # For example, for React: + react: + output: "src/flags/react" # Overrides the default React output directory + # For Go: + go: + package: "github.com/myorg/myrepo/flags" # Overrides the default Go package name + output: "src/flags/go" # Overrides the default Go output directory +``` + +### Configuration Priority + +The CLI uses a layered approach to configuration, allowing you to override settings at different levels. +The configuration is applied in the following order: + +```mermaid +flowchart LR + default("Default Config") + config("Config File") + args("Command Line Args") + default --> config + config --> args +``` + +### Get Involved + +- **CNCF Slack**: Join the conversation in the [#openfeature](https://cloud-native.slack.com/archives/C0344AANLA1) and [#openfeature-cli](https://cloud-native.slack.com/archives/C07DY4TUDK6) channel +- **Regular Meetings**: Attend our [community calls](https://zoom-lfx.platform.linuxfoundation.org/meetings/openfeature) +- **GitHub Issues**: Report bugs or request features in our [issue tracker](https://github.com/open-feature/cli/issues) +- **Social Media**: - Twitter: [@openfeature](https://twitter.com/openfeature) - LinkedIn: [OpenFeature](https://www.linkedin.com/company/openfeature/) -- Join us on [Slack](https://cloud-native.slack.com/archives/C0344AANLA1) -- For more, check out our [community page](https://openfeature.dev/community/) + +For more information, visit our [community page](https://openfeature.dev/community/). + +### Support the project + +- Give this repo a ⭐️! +- Share your experience and contribute back to the project ### Thanks to everyone who has already contributed - - Pictures of the folks who have contributed to the project + + Pictures of the folks who have contributed to the project Made with [contrib.rocks](https://contrib.rocks).