Developer guide and easy setup (opensearch-project#12)

* adds dev guide and required changes for running the plugin inside OSD

Signed-off-by: Shivam Dhar <[email protected]>

Co-authored-by: Shivam Dhar <[email protected]>

.github/workflows/backport.yml

@@ -0,0 +1,28 @@
+name: Backport
+on:
+  pull_request_target:
+    types:
+      - closed
+      - labeled
+
+jobs:
+  backport:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    name: Backport
+    steps:
+      - name: GitHub App token
+        id: github_app_token
+        uses: tibdex/[email protected]
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_PRIVATE_KEY }}
+          installation_id: 22958780
+
+      - name: Backport
+        uses: VachaShah/[email protected]
+        with:
+          github_token: ${{ steps.github_app_token.outputs.token }}
+          branch_name: backport/backport-${{ github.event.number }}

.github/workflows/unit-tests-workflow-for-customImportMap.yml

@@ -42,17 +42,17 @@ jobs:
           echo "Installing yarn ${{ steps.versions_step.outputs.yarn_version }}"
           npm i -g yarn@${{ steps.versions_step.outputs.yarn_version }}
 
-      - name: Move customImportMap to Plugins Dir
-        run: mv src/plugins/custom_import_map OpenSearch-Dashboards/plugins/custom_import_map
+      - name: Move src/plugins/custom_import_map to Plugins Dir
+        run: mv src/ OpenSearch-Dashboards/plugins/
 
       - name: Bootstrap plugin/opensearch-dashboards
         run: |
-          cd OpenSearch-Dashboards/plugins/custom_import_map
+          cd OpenSearch-Dashboards/plugins/src/plugins/custom_import_map
           yarn osd bootstrap
 
       - name: Run tests
         run: |
-          cd OpenSearch-Dashboards/plugins/custom_import_map
+          cd OpenSearch-Dashboards/plugins/src/plugins/custom_import_map
           yarn run test:jest --coverage
 
       - name: Uploads coverage

DEVELOPER_GUIDE.md

@@ -0,0 +1,70 @@
+## Developer Guide
+
+So you want to contribute code to this project? Excellent! We're glad you're here. Here's what you need to do.
+
+- [Forking and Cloning](#forking-and-cloning)
+- [Install Prerequisites](#install-prerequisites)
+- [Setup](#setup)
+- [Run](#run)
+- [Test](#test)
+- [Submitting Changes](#submitting-changes)
+- [Backports](#backports)
+
+### Forking and Cloning
+
+Fork this repository on GitHub, and clone locally with `git clone`.
+
+### Install Prerequisites
+
+You will need to install [node.js](https://nodejs.org/en/), [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md), and [yarn](https://yarnpkg.com/) in your environment to properly pull down dependencies to build and bootstrap the plugin.
+
+
+### Setup
+
+1. Download the OpenSearch Dashboards source code for the [version specified in package.json](./src/plugins/custom_import_map/package.json#L3) you want to set up.
+2. Change your node version to the version specified in `.node-version` inside the OpenSearch Dashboards root directory.
+3. Create a `plugins` directory inside the OpenSearch Dashboards source code directory, if `plugins` directory doesn't exist.
+4. cd into `plugins` directory in the OpenSearch Dashboards source code directory.
+5. Check out this package from version control into the `plugins` directory.
+```bash
+git clone [email protected]:opensearch-project/dashboards-maps.git plugins --no-checkout
+cd plugins
+echo 'src/plugins/custom_import_map/*' >> .git/info/sparse-checkout
+git config core.sparseCheckout true
+git checkout main
+```
+6. Run `yarn osd bootstrap` inside `OpenSearch-Dashboards/plugins/custom_import_map`.
+
+Ultimately, your directory structure should look like this:
+
+```md
+.
+├── OpenSearch-Dashboards
+│   └── plugins
+│       └── src/plugins/custom_import_map
+```
+
+### Run
+
+From OpenSearch-Dashbaords repo (root folder), run the following command -
+- `yarn start`
+
+  Starts OpenSearch Dashboards and includes this plugin. OpenSearch Dashboards will be available on `localhost:5601`.
+
+### Test
+
+From custom_import_map folder running the following command runs the plugin unit tests -
+
+`yarn test:jest`
+
+### Submitting Changes
+
+See [CONTRIBUTING](CONTRIBUTING.md).
+
+### Backports
+
+The Github workflow in [`backport.yml`](.github/workflows/backport.yml) creates backport PRs automatically when the original PR
+with an appropriate label `backport <backport-branch-name>` is merged to main with the backport workflow run successfully on the
+PR. For example, if a PR on main needs to be backported to `1.x` branch, add a label `backport 1.x` to the PR and make sure the
+backport workflow runs on the PR along with other checks. Once this PR is merged to main, the workflow will create a backport PR
+to the `1.x` branch.

src/plugins/custom_import_map/package.json

@@ -3,10 +3,10 @@
   "version": "2.0.0",
   "scripts": {
     "build": "yarn plugin-helpers build",
-    "plugin-helpers": "node ../../scripts/plugin_helpers",
-    "osd": "node ../../scripts/osd",
-    "lint": "node ../../scripts/eslint .",
-    "test:jest": "TZ=UTC ../../node_modules/.bin/jest --config ./test/jest.config.js"
+    "plugin-helpers": "node ../../../../scripts/plugin_helpers",
+    "osd": "node ../../../../scripts/osd",
+    "lint": "node ../../../../scripts/eslint .",
+    "test:jest": "TZ=UTC ../../../../node_modules/.bin/jest --config ./test/jest.config.js"
   },
   "husky": {
     "hooks": {

src/plugins/custom_import_map/public/components/vector_upload_options.test.tsx

@@ -10,7 +10,7 @@ import { fireEvent } from '@testing-library/dom';
 import '@testing-library/jest-dom';
 import * as serviceApiCalls from '../services';
 
-jest.mock('../../../../src/plugins/opensearch_dashboards_react/public', () => ({
+jest.mock('../../../../../../src/plugins/opensearch_dashboards_react/public', () => ({
   useOpenSearchDashboards: jest.fn().mockReturnValue({
     services: {
       http: { post: () => {Promise.resolve({});} },

src/plugins/custom_import_map/public/components/vector_upload_options.tsx

@@ -19,8 +19,8 @@ import {
 } from '@elastic/eui';
 import { getIndex, postGeojson } from '../services';
 import { MAX_FILE_PAYLOAD_SIZE, MAX_FILE_PAYLOAD_SIZE_IN_MB } from '../../common';
-import { toMountPoint, useOpenSearchDashboards } from '../../../../src/plugins/opensearch_dashboards_react/public';
-import { RegionMapOptionsProps } from '../../../../src/plugins/region_map/public';
+import { toMountPoint, useOpenSearchDashboards } from '../../../../../../src/plugins/opensearch_dashboards_react/public';
+import { RegionMapOptionsProps } from '../../../../../../src/plugins/region_map/public';
 
 const VectorUploadOptions = (props: RegionMapOptionsProps) => {
   const opensearchDashboards = useOpenSearchDashboards();

src/plugins/custom_import_map/public/plugin.tsx

@@ -5,20 +5,20 @@
 
 import React from 'react';
 import { i18n } from '@osd/i18n';
-import { CoreSetup, CoreStart, Plugin } from '../../../src/core/public';
+import { CoreSetup, CoreStart, Plugin } from '../../../../../src/core/public';
 import {
   CustomImportMapPluginSetup,
   CustomImportMapPluginStart,
   AppPluginSetupDependencies
 } from './types';
-import { RegionMapVisualizationDependencies } from '../../../src/plugins/region_map/public';
+import { RegionMapVisualizationDependencies } from '../../../../../src/plugins/region_map/public';
 import { VectorUploadOptions } from './components/vector_upload_options';
 
 export class CustomImportMapPlugin
   implements Plugin<CustomImportMapPluginSetup, CustomImportMapPluginStart> {
   public setup(core: CoreSetup, { regionMap }: AppPluginSetupDependencies): CustomImportMapPluginSetup {
 
-    regionMap.addOptionsTab({
+    regionMap.addOptionTab({
       name: 'controls',
       title: i18n.translate(
         'regionMap.mapVis.regionMapEditorConfig.controlTabs.controlsTitle',

src/plugins/custom_import_map/public/services.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { CoreStart } from "../../../src/core/public";
+import { CoreStart } from "../../../../../src/core/public";
 
 export const postGeojson = async (requestBody: any, http: CoreStart['http']) => {
   try {

src/plugins/custom_import_map/public/types.ts

@@ -3,8 +3,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { NavigationPublicPluginStart } from '../../../src/plugins/navigation/public';
-import { RegionMapPluginSetup } from '../../../src/plugins/region_map/public';
+import { NavigationPublicPluginStart } from '../../../../../src/plugins/navigation/public';
+import { RegionMapPluginSetup } from '../../../../../src/plugins/region_map/public';
 
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface CustomImportMapPluginSetup {}

src/plugins/custom_import_map/server/index.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { PluginInitializerContext } from '../../../src/core/server';
+import { PluginInitializerContext } from '../../../../../src/core/server';
 import { CustomImportMapPlugin } from './plugin';
 
 // This exports static code and TypeScript types,

src/plugins/custom_import_map/server/plugin.ts

@@ -9,7 +9,7 @@ import {
   CoreStart,
   Plugin,
   Logger,
-} from '../../../src/core/server';
+} from '../../../../../src/core/server';
 
 import { CustomImportMapPluginSetup, CustomImportMapPluginStart } from './types';
 import { first } from 'rxjs/operators';

src/plugins/custom_import_map/test/jest.config.js

@@ -4,30 +4,30 @@
  */
 
 module.exports = {
-    rootDir: '../',
-    setupFiles: [
-      '<rootDir>/test/polyfills.js',
-      '<rootDir>/test/setupTests.js',
-      '<rootDir>/test/enzyme.js',
-    ],
-    setupFilesAfterEnv: ['<rootDir>/test/setup.jest.js'],
-    modulePaths: ['node_modules', `../../node_modules`],
-    coverageDirectory: './coverage',
-    moduleNameMapper: {
-      '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$': '<rootDir>/test/mocks/styleMock.js',
-      '\\.(css|less|scss)$': '<rootDir>/test/mocks/styleMock.js',
-      '^ui/(.*)': '<rootDir>/../../src/legacy/ui/public/$1/',
-    },
-    snapshotSerializers: ['../../node_modules/enzyme-to-json/serializer'],
-    coverageReporters: ['lcov', 'text', 'cobertura'],
-    testMatch: ['**/*.test.js', '**/*.test.ts', '**/*.test.tsx'],
-    coveragePathIgnorePatterns: [
-      '<rootDir>/build/',
-      '<rootDir>/node_modules/',
-      '<rootDir>/test/'
-    ],
-    clearMocks: true,
-    testPathIgnorePatterns: ['<rootDir>/build/', '<rootDir>/node_modules/'],
-    modulePathIgnorePatterns: [],
-    testEnvironment: 'jest-environment-jsdom',
-  };
+  rootDir: '../',
+  setupFiles: [
+    '<rootDir>/test/polyfills.js',
+    '<rootDir>/test/setupTests.js',
+    '<rootDir>/test/enzyme.js',
+  ],
+  setupFilesAfterEnv: ['<rootDir>/test/setup.jest.js'],
+  modulePaths: ['node_modules', `../../node_modules`],
+  coverageDirectory: './coverage',
+  moduleNameMapper: {
+    '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$': '<rootDir>/test/mocks/styleMock.js',
+    '\\.(css|less|scss)$': '<rootDir>/test/mocks/styleMock.js',
+    '^ui/(.*)': '<rootDir>/../../src/legacy/ui/public/$1/',
+  },
+  snapshotSerializers: ['../../../../node_modules/enzyme-to-json/serializer'],
+  coverageReporters: ['lcov', 'text', 'cobertura'],
+  testMatch: ['**/*.test.js', '**/*.test.ts', '**/*.test.tsx'],
+  coveragePathIgnorePatterns: [
+    '<rootDir>/build/',
+    '<rootDir>/node_modules/',
+    '<rootDir>/test/'
+  ],
+  clearMocks: true,
+  testPathIgnorePatterns: ['<rootDir>/build/', '<rootDir>/node_modules/'],
+  modulePathIgnorePatterns: [],
+  testEnvironment: 'jest-environment-jsdom',
+};