From 50317b9e0941af7ef3e7a11d04eb16fe1edffaae Mon Sep 17 00:00:00 2001 From: Shivam Dhar Date: Thu, 23 Jun 2022 09:56:48 -0700 Subject: [PATCH] Developer guide and easy setup (#12) * adds dev guide and required changes for running the plugin inside OSD Signed-off-by: Shivam Dhar Co-authored-by: Shivam Dhar --- .github/workflows/backport.yml | 28 ++++++++ ...nit-tests-workflow-for-customImportMap.yml | 8 +-- DEVELOPER_GUIDE.md | 70 +++++++++++++++++++ src/plugins/custom_import_map/package.json | 8 +-- .../components/vector_upload_options.test.tsx | 2 +- .../components/vector_upload_options.tsx | 4 +- .../custom_import_map/public/plugin.tsx | 6 +- .../custom_import_map/public/services.ts | 2 +- src/plugins/custom_import_map/public/types.ts | 4 +- src/plugins/custom_import_map/server/index.ts | 2 +- .../custom_import_map/server/plugin.ts | 2 +- .../custom_import_map/test/jest.config.js | 54 +++++++------- 12 files changed, 144 insertions(+), 46 deletions(-) create mode 100644 .github/workflows/backport.yml create mode 100644 DEVELOPER_GUIDE.md diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml new file mode 100644 index 00000000..cc046cc5 --- /dev/null +++ b/.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/github-app-token@v1.5.0 + with: + app_id: ${{ secrets.APP_ID }} + private_key: ${{ secrets.APP_PRIVATE_KEY }} + installation_id: 22958780 + + - name: Backport + uses: VachaShah/backport@v1.1.4 + with: + github_token: ${{ steps.github_app_token.outputs.token }} + branch_name: backport/backport-${{ github.event.number }} \ No newline at end of file diff --git a/.github/workflows/unit-tests-workflow-for-customImportMap.yml b/.github/workflows/unit-tests-workflow-for-customImportMap.yml index 1dbf514f..1fced466 100644 --- a/.github/workflows/unit-tests-workflow-for-customImportMap.yml +++ b/.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 diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md new file mode 100644 index 00000000..8b94c925 --- /dev/null +++ b/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 git@github.com: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 ` 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. \ No newline at end of file diff --git a/src/plugins/custom_import_map/package.json b/src/plugins/custom_import_map/package.json index 0b1957e0..00ecf7f9 100644 --- a/src/plugins/custom_import_map/package.json +++ b/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": { diff --git a/src/plugins/custom_import_map/public/components/vector_upload_options.test.tsx b/src/plugins/custom_import_map/public/components/vector_upload_options.test.tsx index 7de4db51..c4080182 100644 --- a/src/plugins/custom_import_map/public/components/vector_upload_options.test.tsx +++ b/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({});} }, diff --git a/src/plugins/custom_import_map/public/components/vector_upload_options.tsx b/src/plugins/custom_import_map/public/components/vector_upload_options.tsx index caced72a..9e839de6 100644 --- a/src/plugins/custom_import_map/public/components/vector_upload_options.tsx +++ b/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(); diff --git a/src/plugins/custom_import_map/public/plugin.tsx b/src/plugins/custom_import_map/public/plugin.tsx index 168f8c27..c137883a 100644 --- a/src/plugins/custom_import_map/public/plugin.tsx +++ b/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 { public setup(core: CoreSetup, { regionMap }: AppPluginSetupDependencies): CustomImportMapPluginSetup { - regionMap.addOptionsTab({ + regionMap.addOptionTab({ name: 'controls', title: i18n.translate( 'regionMap.mapVis.regionMapEditorConfig.controlTabs.controlsTitle', diff --git a/src/plugins/custom_import_map/public/services.ts b/src/plugins/custom_import_map/public/services.ts index 66561a30..aeedf84b 100644 --- a/src/plugins/custom_import_map/public/services.ts +++ b/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 { diff --git a/src/plugins/custom_import_map/public/types.ts b/src/plugins/custom_import_map/public/types.ts index 8e26cd74..f1266b7d 100644 --- a/src/plugins/custom_import_map/public/types.ts +++ b/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 {} diff --git a/src/plugins/custom_import_map/server/index.ts b/src/plugins/custom_import_map/server/index.ts index b230f714..7adea51f 100644 --- a/src/plugins/custom_import_map/server/index.ts +++ b/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, diff --git a/src/plugins/custom_import_map/server/plugin.ts b/src/plugins/custom_import_map/server/plugin.ts index 54dc0710..80eabc91 100644 --- a/src/plugins/custom_import_map/server/plugin.ts +++ b/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'; diff --git a/src/plugins/custom_import_map/test/jest.config.js b/src/plugins/custom_import_map/test/jest.config.js index 6089d8c8..101fe018 100644 --- a/src/plugins/custom_import_map/test/jest.config.js +++ b/src/plugins/custom_import_map/test/jest.config.js @@ -4,30 +4,30 @@ */ module.exports = { - rootDir: '../', - setupFiles: [ - '/test/polyfills.js', - '/test/setupTests.js', - '/test/enzyme.js', - ], - setupFilesAfterEnv: ['/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)$': '/test/mocks/styleMock.js', - '\\.(css|less|scss)$': '/test/mocks/styleMock.js', - '^ui/(.*)': '/../../src/legacy/ui/public/$1/', - }, - snapshotSerializers: ['../../node_modules/enzyme-to-json/serializer'], - coverageReporters: ['lcov', 'text', 'cobertura'], - testMatch: ['**/*.test.js', '**/*.test.ts', '**/*.test.tsx'], - coveragePathIgnorePatterns: [ - '/build/', - '/node_modules/', - '/test/' - ], - clearMocks: true, - testPathIgnorePatterns: ['/build/', '/node_modules/'], - modulePathIgnorePatterns: [], - testEnvironment: 'jest-environment-jsdom', - }; + rootDir: '../', + setupFiles: [ + '/test/polyfills.js', + '/test/setupTests.js', + '/test/enzyme.js', + ], + setupFilesAfterEnv: ['/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)$': '/test/mocks/styleMock.js', + '\\.(css|less|scss)$': '/test/mocks/styleMock.js', + '^ui/(.*)': '/../../src/legacy/ui/public/$1/', + }, + snapshotSerializers: ['../../../../node_modules/enzyme-to-json/serializer'], + coverageReporters: ['lcov', 'text', 'cobertura'], + testMatch: ['**/*.test.js', '**/*.test.ts', '**/*.test.tsx'], + coveragePathIgnorePatterns: [ + '/build/', + '/node_modules/', + '/test/' + ], + clearMocks: true, + testPathIgnorePatterns: ['/build/', '/node_modules/'], + modulePathIgnorePatterns: [], + testEnvironment: 'jest-environment-jsdom', +};