diff --git a/README.md b/README.md index 26345a543ea2..95fd2615de3a 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ # [Flagsmith](https://flagsmith.com/) is an Open-Source Feature Flagging Tool to Ship Faster & Control Releases -Change the way your team releases software. Roll out, segment, and optimise—with granular control. Stay secure with on-premise and private cloud hosting. +Change the way your team releases software. Roll out, segment, and optimise—with granular control. Stay secure with on-premise and private cloud hosting. * Feature flags: Release features behind the safety of a feature flag * Make changes remotely: Easily toggle individual features on and off, and make changes without deploying new code diff --git a/docs/docs/getting-started/_category_.json b/docs/docs/getting-started/_category_.json new file mode 100644 index 000000000000..571b4d7babfd --- /dev/null +++ b/docs/docs/getting-started/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Getting Started", + "position": 2, + "collapsed": true +} diff --git a/docs/docs/getting-started/feature-flags.md b/docs/docs/getting-started/feature-flags.md new file mode 100644 index 000000000000..aabb59c8fd29 --- /dev/null +++ b/docs/docs/getting-started/feature-flags.md @@ -0,0 +1,42 @@ +--- +title: Feature Flags +sidebar_label: Feature Flags +sidebar_position: 1 +--- + +Feature Flags are a development methodology that allow you to ship code and features in your application before they are finished. A feature flag is a control point in your code that determines whether a particular feature or behaviour is active. Flags can be simple on/off (boolean) switches, or multivariate, allowing you to select from multiple options or variants. + +### What do Feature Flags enable? + +- **Decouple deployment from release:** Ship code to production with features hidden behind flags, then enable them for users when ready. + +- **Staged rollouts:** Gradually enable features for a subset of users, reducing risk and allowing for real-world testing. [Learn more](/guides-and-examples/staged-feature-rollouts.md) + +- **A/B testing and experimentation:** Test multiple variants of a feature and measure impact. [Learn more](/advanced-use/ab-testing.md) + +- **Remote configuration:** Change app behaviour or configuration in real time, without redeploying. + +### Advantages of using Feature Flags + +- **Safer releases:** Reduce the risk of deploying new features by controlling exposure. +- **Faster iteration:** Test and iterate on features quickly, without waiting for deployment cycles. +- **Targeted rollouts:** Enable features for specific users, groups, or environments. +- **Easy rollback:** Instantly turn off features if bugs or issues are detected. +- **Experimentation:** Run experiments and gather data to inform product decisions. + +### Workflow + +1. You are about to start work on a new feature. Let's imagine you are going to implement a sharing button with your application. + +2. Create a new feature flag in Flagsmith, calling it "sharing_button". Set it to enabled on your development environment, and disabled on your production environment. + +3. Start working on the feature. Whenever you write code that shows the button within the UI, wrap it in a conditional statement, testing against the value of the flag "sharing button". Only show the button if the flag is enabled. + +4. Because your button only shows when the "sharing_button" flag is enabled, you are safe to deploy your code as you work on the feature. Your code will be live within the production platform, but the functionality is hidden behind the flag. + +5. Once you are happy with your feature, you can enable the "sharing_button" for other members of your team and with beta testers. + +6. If everything is working as intended, enable the "sharing_button" flag for everyone in your production environment, and your feature is rolled out. + +If you want to learn more about Feature Flags, +[Flickr wrote the seminal blog post on it in 2009](https://code.flickr.net/2009/12/02/flipping-out/). diff --git a/docs/docs/getting-started/glossary.md b/docs/docs/getting-started/glossary.md new file mode 100644 index 000000000000..0907582076ad --- /dev/null +++ b/docs/docs/getting-started/glossary.md @@ -0,0 +1,43 @@ +--- +title: Glossary +sidebar_label: Glossary +sidebar_position: 3 +--- + +This glossary provides concise definitions for some of the key concepts within Flagsmith: + +- [**A/B Testing**](/advanced-use/ab-testing.md): A method of testing different feature variants with different user groups, often implemented using multivariate flags and percentage splits. + +- [**Core API**](/edge-api/Overview.md#core-api): Flagsmith's private API for programmatic control of the platform. + +- [**Edge API**](/advanced-use/edge-api.md): Flagsmith's publicly accessible API, specifically intended for use with our SDKs. + +- [**Edge Proxy**](/advanced-use/edge-proxy.md): A self-hosted service that provides a local, low-latency interface to the Flagsmith API. + +- [**Environment**](/basic-features/index.md#environments): Environments are a way to separate the configuration of your features. A project can have any number of environments. + +- [**Environment Document**](/clients/index.md#the-environment-document): A JSON document containing all configuration for feature flags in an environment. + +- [**Feature**](/basic-features/managing-features.md): A configuration that can be enabled, disabled, or set to a specific value. Features are shared across all Environments in a project, but their values/states can be modified between Environments. + +- [**Feature Flag**](/basic-features/index.md): A boolean or multivariate switch to enable/disable features or set their values dynamically without deploying code. + +- [**Identity**](/basic-features/managing-identities.md): An entity within a particular environment, against which you can manage and override feature settings. + +- [**Local Evaluation Mode**](/clients/index.md#local-evaluation): A mode where the SDK evaluates feature flags locally using a downloaded environment document, reducing latency and API calls. + +- [**Multivariate Flag**](/basic-features/managing-features.md#multi-variate-flags): A feature flag that can take on multiple values (not just on/off), useful for A/B testing. + +- [**Organisation**](/basic-features/index.md#organisations): Organisations are a way for you and other team members to manage projects and their features. Users can be members of multiple organisations. + +- [**Project**](/basic-features/index.md#projects): Projects contain one or more Environments that share a single set of Features across all of the Environments within the Project. Organisations can have any number of Projects. + +- [**Role-Based Access Control (RBAC)**](/system-administration/rbac.md): A system for managing user permissions and access within an organisation. + +- [**SDK (Software Development Kit)**](/clients/): Client libraries provided by Flagsmith for integrating feature flagging into applications. + +- [**Segment**](/basic-features/segments.md): A group of identities defined by traits (e.g., logins, device, location, or custom traits). You can override feature defaults for segments, such as enabling features for a "power user" group. + +- [**Staged Rollout**](/guides-and-examples/staged-feature-rollouts.md): Gradually enabling a feature for increasing percentages of your identities to reduce risk. + +- [**Trait**](/basic-features/managing-identities.md#identity-traits): A key-value pair associated with an identity that can store any type of data. diff --git a/docs/docs/getting-started/quick-start.md b/docs/docs/getting-started/quick-start.md new file mode 100644 index 000000000000..f03749bc9b75 --- /dev/null +++ b/docs/docs/getting-started/quick-start.md @@ -0,0 +1,187 @@ +--- +title: Quick Start +sidebar_label: Quick Start +sidebar_position: 2 +--- + +import CodeBlock from '@theme/CodeBlock'; import { JsVersion } from '@site/src/components/SdkVersions.js'; + +# Flagsmith Quick Start Guide + +This tutorial will guide you through the core concepts of integrating Flagsmith into your application. + +## Learning objectives + +By the end of this tutorial, you will be able to: + +- Create a Project and your first flag in the Flagsmith dashboard. +- Import the Flagsmith JavaScript SDK into your web page. +- Connect to the Flagsmith API and retrieve your flags. +- Update your application's behaviour based on a flag's value. + +## Prerequisites + +You will need access to a Flagsmith instance (either using the SaaS platform or self-hosted) and a basic understanding of HTML and JavaScript. + +:::tip +If you're using the SaaS platform, log in at [app.flagsmith.com](https://app.flagsmith.com/). If you're self-hosting, log in to your deployed instance. +::: + +## 1. Create a Project and Flag in the Dashboard + +We are going to create an organisation (if you haven't already), a project, and your first flag. + + + +Flagsmith manages Flags with Projects, so let's create one now: + + + +Flagsmith organises Projects into separate Environments. When you create a Project, Flagsmith automatically creates `Development` and `Production` Environments. We will come to these Environments later. Let us go ahead and create our first Flag. This flag will control whether a button shows on our web page. + + + +Flags within Flagsmith are a combination of both: A Boolean value - the `Flag State` and then optionally: A String/Integer/Boolean value - the `Flag Value`. For now, we're only going to use the `Boolean` value of the flag to control whether the button shows. Create a flag called `show_demo_button`, and leave it as Disabled by default: + + + +## 2. Import the Javascript SDK + +Ok, so we have set up our flag; now let us bring it into our application. We have a (quite small!) web page: + +```html + + +
+ +

