Update documentation for configuring feature flag clients

Clarify that app name needs to be the running application environment

doc/operations/feature_flags.md

@@ -196,9 +196,11 @@ To get the access credentials that your application needs to communicate with Gi
 1. Click the **Configure** button to view the following:
    - **API URL**: URL where the client (application) connects to get a list of feature flags.
    - **Instance ID**: Unique token that authorizes the retrieval of the feature flags.
-   - **Application name**: The name of the running environment. For instance,
-     if the application runs for a production server, the application name would be
-     `production` or similar. This value is used for the environment spec evaluation.
+   - **Application name**: The name of the *environment* the application runs in
+     (not the name of the application itself).
+
+     For example, if the application runs for a production server, the **Application name**
+     could be `production` or similar. This value is used for the environment spec evaluation.
 
 NOTE: **Note:**
 The meaning of these fields might change over time. For example, we are not sure
@@ -247,7 +249,7 @@ func init() {
     unleash.Initialize(
         unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"),
         unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"),
-        unleash.WithAppName("production"),
+        unleash.WithAppName("production"), // Set to the running environment of your application
         unleash.WithListener(&metricsInterface{}),
     )
 }
@@ -280,7 +282,7 @@ require 'unleash/context'
 
 unleash = Unleash::Client.new({
   url: 'http://gitlab.com/api/v4/feature_flags/unleash/42',
-  app_name: 'production',
+  app_name: 'production', # Set to the running environment of your application
   instance_id: '29QmjsW6KngPR5JNPMWx'
 })
 

ee/app/assets/javascripts/feature_flags/components/configure_feature_flags_modal.vue

 <script>
-import { GlModal, GlDeprecatedButton, GlTooltipDirective, GlLoadingIcon } from '@gitlab/ui';
+import {
+  GlModal,
+  GlDeprecatedButton,
+  GlTooltipDirective,
+  GlLoadingIcon,
+  GlSprintf,
+  GlLink,
+} from '@gitlab/ui';
 import { s__, __, sprintf } from '~/locale';
 import ModalCopyButton from '~/vue_shared/components/modal_copy_button.vue';
 import Icon from '~/vue_shared/components/icon.vue';
@@ -24,6 +31,8 @@ export default {
     Icon,
     Callout,
     GlLoadingIcon,
+    GlSprintf,
+    GlLink,
   },
 
   directives: {
@@ -35,7 +44,11 @@ export default {
       type: String,
       required: true,
     },
-    helpAnchor: {
+    helpClientLibrariesPath: {
+      type: String,
+      required: true,
+    },
+    helpClientExamplePath: {
       type: String,
       required: true,
     },
@@ -73,7 +86,7 @@ export default {
           'FeatureFlags|Install a %{docs_link_anchored_start}compatible client library%{docs_link_anchored_end} and specify the API URL, application name, and instance ID during the configuration setup. %{docs_link_start}More Information%{docs_link_end}',
         ),
         {
-          docs_link_anchored_start: `<a href="${this.helpAnchor}" target="_blank">`,
+          docs_link_anchored_start: `<a href="${this.helpClientLibrariesPath}" target="_blank">`,
           docs_link_anchored_end: '</a>',
           docs_link_start: `<a href="${this.helpPath}" target="_blank">`,
           docs_link_end: '</a>',
@@ -167,5 +180,18 @@ export default {
       category="info"
       :message="$options.instanceIdRegenerateText"
     />
+    <callout category="warning">
+      <gl-sprintf
+        :message="
+          s__(
+            'FeatureFlags|Set the Unleash client application name to the name of the environment your application runs in. This value is used to match environment scopes. See the %{linkStart}example client configuration%{linkEnd}.',
+          )
+        "
+      >
+        <template #link="{ content }">
+          <gl-link :href="helpClientExamplePath" target="_blank">{{ content }}</gl-link>
+        </template>
+      </gl-sprintf>
+    </callout>
   </gl-modal>
 </template>

ee/app/assets/javascripts/feature_flags/components/feature_flags.vue

@@ -66,7 +66,11 @@ export default {
       type: String,
       required: true,
     },
-    featureFlagsAnchoredHelpPagePath: {
+    featureFlagsClientLibrariesHelpPagePath: {
+      type: String,
+      required: true,
+    },
+    featureFlagsClientExampleHelpPagePath: {
       type: String,
       required: true,
     },
@@ -243,7 +247,8 @@ export default {
     <configure-feature-flags-modal
       v-if="canUserConfigure"
       :help-path="featureFlagsHelpPagePath"
-      :help-anchor="featureFlagsAnchoredHelpPagePath"
+      :help-client-libraries-path="featureFlagsClientLibrariesHelpPagePath"
+      :help-client-example-path="featureFlagsClientExampleHelpPagePath"
       :api-url="unleashApiUrl"
       :instance-id="instanceId"
       :is-rotating="isRotating"

ee/app/assets/javascripts/feature_flags/index.js

@@ -20,7 +20,9 @@ export default () =>
           projectId: this.dataset.projectId,
           errorStateSvgPath: this.dataset.errorStateSvgPath,
           featureFlagsHelpPagePath: this.dataset.featureFlagsHelpPagePath,
-          featureFlagsAnchoredHelpPagePath: this.dataset.featureFlagsAnchoredHelpPagePath,
+          featureFlagsClientLibrariesHelpPagePath: this.dataset
+            .featureFlagsClientLibrariesHelpPagePath,
+          featureFlagsClientExampleHelpPagePath: this.dataset.featureFlagsClientExampleHelpPagePath,
           unleashApiUrl: this.dataset.unleashApiUrl,
           unleashApiInstanceId: this.dataset.unleashApiInstanceId || '',
           csrfToken: csrf.token,

ee/app/views/projects/feature_flags/index.html.haml

@@ -3,8 +3,9 @@
 #feature-flags-vue{ data: { endpoint: project_feature_flags_path(@project, format: :json),
   "project-id" => @project.id,
   "error-state-svg-path" => image_path('illustrations/feature_flag.svg'),
-  "feature-flags-help-page-path" => help_page_path("user/project/operations/feature_flags"),
-  "feature-flags-anchored-help-page-path" => help_page_path("user/project/operations/feature_flags", anchor: "client-libraries"),
+  "feature-flags-help-page-path" => help_page_path("operations/feature_flags"),
+  "feature-flags-client-libraries-help-page-path" => help_page_path("operations/feature_flags", anchor: "choose-a-client-library"),
+  "feature-flags-client-example-help-page-path" => help_page_path("operations/feature_flags", anchor: "golang-application-example"),
   "unleash-api-url" => (unleash_api_url(@project) if can?(current_user, :admin_feature_flag, @project)),
   "unleash-api-instance-id" => (unleash_api_instance_id(@project) if can?(current_user, :admin_feature_flag, @project)),
   "can-user-admin-feature-flag" => can?(current_user, :admin_feature_flag, @project),

ee/changelogs/unreleased/ff-app-name-instructions.yml

+---
+title: Clarify that Unleash client app name must be the running environment name
+merge_request: 37255
+author:
+type: other

ee/spec/frontend/feature_flags/components/configure_feature_flags_modal_spec.js

@@ -11,7 +11,8 @@ describe('Configure Feature Flags Modal', () => {
   beforeEach(() => {
     propsData = {
       helpPath: '/help/path',
-      helpAnchor: '/help/path/#flags',
+      helpClientLibrariesPath: '/help/path/#flags',
+      helpClientExamplePath: '/feature-flags#clientexample',
       apiUrl: '/api/url',
       instanceId: 'instance-id-token',
       isRotating: false,

ee/spec/frontend/feature_flags/components/feature_flags_spec.js

@@ -21,7 +21,8 @@ describe('Feature flags', () => {
     csrfToken: 'testToken',
     errorStateSvgPath: '/assets/illustrations/feature_flag.svg',
     featureFlagsHelpPagePath: '/help/feature-flags',
-    featureFlagsAnchoredHelpPagePath: '/help/feature-flags#unleash-clients',
+    featureFlagsClientLibrariesHelpPagePath: '/help/feature-flags#unleash-clients',
+    featureFlagsClientExampleHelpPagePath: '/help/feature-flags#client-example',
     userListsApiDocPath: '/help/api/user_lists',
     unleashApiUrl: `${TEST_HOST}/api/unleash`,
     unleashApiInstanceId: 'oP6sCNRqtRHmpy1gw2-F',
@@ -96,7 +97,8 @@ describe('Feature flags', () => {
       featureFlagsHelpPagePath: '/help/feature-flags',
       canUserConfigure: false,
       canUserRotateToken: false,
-      featureFlagsAnchoredHelpPagePath: '/help/feature-flags#unleash-clients',
+      featureFlagsClientLibrariesHelpPagePath: '/help/feature-flags#unleash-clients',
+      featureFlagsClientExampleHelpPagePath: '/help/feature-flags#client-example',
       unleashApiUrl: `${TEST_HOST}/api/unleash`,
       unleashApiInstanceId: 'oP6sCNRqtRHmpy1gw2-F',
       projectId: '8',

locale/gitlab.pot

@@ -10309,6 +10309,9 @@ msgstr ""
 msgid "FeatureFlags|Rollout Strategy"
 msgstr ""
 
+msgid "FeatureFlags|Set the Unleash client application name to the name of the environment your application runs in. This value is used to match environment scopes. See the %{linkStart}example client configuration%{linkEnd}."
+msgstr ""
+
 msgid "FeatureFlags|Status"
 msgstr ""