feat(flagpole): Adds core flagpole documentation (#1297)

Co-authored-by: Mark Story <[email protected]>

src/docs/feature-flags/flagpole.mdx

@@ -0,0 +1,137 @@
+# Flagpole
+Flagpole is Sentry's internal, options-backed feature flagging library. 
+
+Features are defined in the [`sentry-options-automator`](https://github.com/getsentry/sentry-options-automator) repository as yaml objects within the [`options/defaults/flagpole.yml`](https://github.com/getsentry/sentry-options-automator/blob/main/options/default/flagpole.yml) file.
+These yaml options are pushed to each of our deployments and stored in a database table, where they are later queried and parsed during feature flag evaluation.
+
+Here's the example configuration for a feature named `organizations:is_sentry`, which is enabled for an organization with the slug `sentry`.
+```yaml
+options:
+  'feature.organizations:is_sentry':
+    created_at: '2024-06-01T00:00:00.000000'
+    enabled: false
+    owner: hybrid-cloud
+    segments:
+    - conditions:
+      - operator: in
+        value:
+          - sentry
+        property: organization_slug
+      name: is_sentry
+      rollout: 100
+```
+
+## Flagpole Feature Yaml Structure
+
+`created_at`
+
+: The ISO 8601 datetime of when the feature was added to the config yaml.
+
+`owner`
+
+: The team name or email of the user that owns this feature flag
+
+`enabled` [optional]
+
+: The global toggle for the feature flag. Defaults to `True`. Setting this to `False` can be a break-glass safety valve to disable a feature without having to modify existing segments or conditions.
+
+`segments`
+
+: A wrapper around a list of conditions, acting as a logical grouping of customers/entities to enable the feature flag for. If no segments are defined, the feature will evaluate to `True`. Segments allow you to create `OR` operations with other segments. At least one segment must evaluate to `True` for a feature to be granted.
+
+### Segments
+`conditions`
+
+: A list of predicates to evaluate for the feature flag to be enabled for this segment. All conditions in a segment must be evaluate to `True` in order for the segment to be enabled. If no conditions are defined, the segment will evaluate to `False`.
+
+`name`
+
+: A brief description of the segment identifying its intended purpose.
+
+`rollout` [optional]
+
+: A percentage of entities to enable the feature for, defined as an integer between `0` - `100`. Defaults to `100`.
+
+
+### Conditions
+`property`
+
+: The property name of the evaluation context entry to match against.
+
+`value`
+
+: The expected value to compare against the evaluation context's property value, using the provided operator. 
+
+`operator`
+
+: The comparison strategy to apply between the evaluation context's property value and the provided condition value.
+
+
+### Operators
+Flagpole currently supports the following `operator` types:
+
+`in`
+
+: Given a list of values, evaluates to `True` if the context property value exists in the list.
+
+`not_in`
+
+: The inverse of `in`, evaluates to `True` if the context property value does not exist in the provided list.
+
+`contains`
+
+: Given a single int, string, float, or boolean value, evalutes to `True` if the context property value is a list containing the provided value.
+
+`not_contains`
+
+: The inverse of `contains`, evalutes to `True` if the context property value is a list which does not contain the provided value.
+
+`equals`
+
+: Given a single int, string, float, or boolean value, evaluates to `True` if the context property value exactly matches the provided value.
+
+`not_equals`
+
+: The inverse of `equals`, evaluates to `True` if the context property value does not match the provided value.
+
+## Evaluation Contexts
+When a feature flag is checked, the caller must provide one or more entity objects for the feature handler to match against.  These objects are used to construct an `EvaluationContext`, which is essentially a flat dictionary of keys and primitive values. This context is passed to each feature, which provides this context to each segment and condition to enforce whether the feature should be enabled.
+
+### Context Builders
+Each evaluation context is built up in stages via a [`ContextBuilder`](https://github.com/getsentry/sentry/blob/3cbf73a389a4ea006cbad9d8c4b8073effe09393/src/flagpole/evaluation_context.py#L54) object.
+
+Each context builder consists of a list of context transformers, which are responsible for creating individual slices of the larger evaluation context.
+
+## Rolling out a new Flagpole feature
+
+Creating a new Flagpole Feature is currently a 3 step process:
+1. Register a new feature in GetSentry's `features.py` file with the Flagpole strategy:
+```python
+features.add(
+    "<feature_scope>:<feature_name>",
+    OrganizationFeature,
+    FeatureHandlerStrategy.FLAGPOLE
+)
+```
+
+2. Add a new feature object entry to sentry-options-automator's `flagpole.yml` file. The feature's option name must follow the following format in order to be picked up by Flagpole:
+
+`feature.<feature_scope>:<feature_name>`.
+
+3. Add the feature name to the `flagpole.flagpole_only_features` list in sentry-options-automator's default [`app.yaml`](https://github.com/getsentry/sentry-options-automator/blob/483737d45dbc68253e926c3f860b5ae33111697b/options/default/app.yaml#L219) file, omitting the `feature.` prefix.
+
+Once the option change is deployed, the feature checks will immediately be active in all environments and regions.
+
+
+## Testing a Flagpole feature locally
+You can test a flagpole feature flag locally using the GetSentry devserver. Because the feature handler for Flagpole only exists in GetSentry, it's not currently possible to test Sentry-only flagpole features.
+
+Start by creating a new yaml file containing your feature config.
+
+You can push your feature option to your local devserver using the following `getsentry` CLI command:
+
+```bash
+getsentry configoptions -f <path>/<to>/<your>/<config>.yml -l DEBUG patch
+```
+
+If this command runs successfully, your flagpole feature should now be active in your local devserver instance and will persist across runs until you remove the feature option.