add descriptions on how the PR solved the problme

Signed-off-by: Yulong Ruan <[email protected]>

src/plugins/management/public/management_sections_service.test.ts

@@ -107,13 +107,15 @@ describe('ManagementService', () => {
     `);
   });
 
-  it('should disable apps register in opensearchDashboards section', () => {
+  it('should disable apps register in predefined opensearchDashboards section', () => {
+    // The management capabilities has `opensearchDashboards` as the key
     const originalDataSourcesCapability =
       DEFAULT_MANAGEMENT_CAPABILITIES.management.opensearchDashboards.dataSources;
 
     const setup = managementService.setup();
 
-    // Register app with id dataSources, the app id will be capability id
+    // The predefined opensearchDashboards section has id `opensearch-dashboards` which
+    // doesn't match the capability id `opensearchDashboards`
     setup.section.opensearchDashboards.registerApp({
       id: 'dataSources',
       title: 'Data source',

src/plugins/management/public/management_sections_service.ts

@@ -51,6 +51,18 @@ const [getSectionsServiceStartPrivate, setSectionsServiceStartPrivate] = createG
   ManagementSectionsStartPrivate
 >('SectionsServiceStartPrivate');
 
+/**
+ * The management capabilities has `opensearchDashboards` as the key
+ * While when registering the opensearchDashboards section, the section id is `opensearch-dashboards`
+ * as defined in {@link ManagementSectionId.OpenSearchDashboards} and section id is used as the capability
+ * id. Here we have a mapping so that the section id opensearch-dashboards can mapping correctly back to the
+ * capability id: opensearchDashboards
+ *
+ * Why not directly change the capability id to opensearch-dashboards?
+ * The issue was introduced in https://github.com/opensearch-project/OpenSearch-Dashboards/pull/260
+ * Since then, the capability id `opensearchDashboards` has been used by plugins, having a mapping here
+ * is for backward compatibility
+ */
 const MANAGEMENT_ID_TO_CAPABILITIES: Record<string, string> = {
   'opensearch-dashboards': 'opensearchDashboards',
 };