diff options
Diffstat (limited to 'doc/development/ee_features.md')
| -rw-r--r-- | doc/development/ee_features.md | 104 |
1 files changed, 94 insertions, 10 deletions
diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 2bf8ad81ba4..10943b2d135 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -18,19 +18,103 @@ info: To determine the technical writer assigned to the Stage/Group associated w [EE features list](https://about.gitlab.com/features/). <!-- markdownlint-enable MD044 --> -## SaaS only feature +## SaaS-only feature Use the following guidelines when you develop a feature that is only applicable for SaaS (for example, a CustomersDot integration). -1. It is recommended you use an application setting. This enables - granular settings so that each SaaS instance can switch things according to - their need. -1. If application setting is not possible, helpers such as `Gitlab.com?` can be - used. However, this comes with drawbacks as listed in the epic to - [remove these helpers](https://gitlab.com/groups/gitlab-org/-/epics/7374). - 1. Consider performance and availability impact on other SaaS instances. For example, - [GitLab JH overrides](https://jihulab.com/gitlab-cn/gitlab/-/blob/main-jh/jh/lib/jh/gitlab/saas.rb) - SaaS helpers, so that it returns true for `Gitlab.com?`. +In general, features should be provided for [both SaaS and self-managed deployments](https://about.gitlab.com/handbook/product/product-principles/#parity-between-saas-and-self-managed-deployments). +However, there are cases when a feature should only be available on SaaS and this guide will help show how that is +accomplished. + +It is recommended you use `Gitlab::Saas.feature_available?`. This enables +context rich definitions around the reason the feature is SaaS-only. + +### Implementing a SaaS-only feature with `Gitlab::Saas.feature_available?` + +#### Adding to the FEATURES constant + +1. See the [namespacing concepts guide](software_design.md#use-namespaces-to-define-bounded-contexts) + for help in naming a new SaaS-only feature. +1. Add the new feature to `FEATURE` in `ee/lib/ee/gitlab/saas.rb`. + + ```ruby + FEATURES = %w[purchases/additional_minutes some_domain/new_feature_name].freeze + ``` + +1. Use the new feature in code with `Gitlab::Saas.feature_available?('some_domain/new_feature_name')`. + +#### SaaS-only feature definition and validation + +This process is meant to ensure consistent SaaS feature usage in the codebase. All SaaS features **must**: + +- Be known. Only use SaaS features that are explicitly defined. +- Have an owner. + +All SaaS features are self-documented in YAML files stored in: + +- [`ee/config/saas_features`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/config/saas_features) + +Each SaaS feature is defined in a separate YAML file consisting of a number of fields: + +| Field | Required | Description | +|---------------------|----------|--------------------------------------------------------------------------------------------------------------| +| `name` | yes | Name of the SaaS feature. | +| `introduced_by_url` | no | The URL to the merge request that introduced the SaaS feature. | +| `milestone` | no | Milestone in which the SaaS feature was created. | +| `group` | no | The [group](https://about.gitlab.com/handbook/product/categories/#devops-stages) that owns the feature flag. | + +### Opting out of a SaaS-only feature on another SaaS instance (JiHu) + +Prepend the `ee/lib/ee/gitlab/saas.rb` module and override the `Gitlab::Saas.feature_available?` method. + +```ruby +JH_DISABLED_FEATURES = %w[some_domain/new_feature_name].freeze + +override :feature_available? +def feature_available?(feature) + super && JH_DISABLED_FEATURES.exclude?(feature) +end +``` + +### Do not use SaaS-only features for functionality in CE + +`Gitlab::Saas.feature_vailable?` must not appear in CE. +See [extending CE with EE guide](#extend-ce-features-with-ee-backend-code). + +### SaaS-only features in tests + +Introducing a SaaS-only feature into the codebase creates an additional code path that should be tested. +It is strongly advised to include automated tests for all code affected by a SaaS-only feature, both when **enabled** and **disabled** +to ensure the feature works properly. + +To enable a SaaS-only feature in a test, use the `stub_saas_features` +helper. For example, to globally disable the `purchases/additional_minutes` feature +flag in a test: + +```ruby +stub_saas_features('purchases/additional_minutes' => false) + +::Gitlab::Saas.feature_available?('purchases/additional_minutes') # => false +``` + +A common pattern of testing both paths looks like: + +```ruby +it 'purchases/additional_minutes is not available' do + # tests assuming purchases/additional_minutes is not enabled by default + ::Gitlab::Saas.feature_available?('purchases/additional_minutes') # => false +end + +context 'when purchases/additional_minutes is available' do + before do + stub_saas_features('purchases/additional_minutes' => true) + end + + it 'returns true' do + ::Gitlab::Saas.feature_available?('purchases/additional_minutes') # => true + end +end +``` ### Simulate a SaaS instance |