From 9111c6891f2bc408330ddc2fdbc0ff383fd62268 Mon Sep 17 00:00:00 2001 From: Keaton Sentak <54916859+ksentak@users.noreply.github.com> Date: Thu, 26 Oct 2023 08:49:59 -0400 Subject: [PATCH] Add Versioning to Mock Firebolt & Clean Up (#144) * add versioning to app * update docs & remove discovery openrpc * update changelog * re-add npm run dev command --- CHANGELOG.md | 30 +++++++- Dockerfile | 2 +- README.md | 31 ++------ conduit/package-lock.json | 21 +----- conduit/package.json | 5 +- docs/DotConfig.md | 19 ++--- docs/Overview.md | 4 +- docs/ProxyMode.md | 2 +- docs/Triggers.md | 2 +- docs/Versioning.md | 90 ++++++++++++++++++++++++ functional/package-lock.json | 4 +- functional/package.json | 2 +- functional/tests/utilities.mjs | 2 +- package-lock.json | 6 -- server/README.md | 9 +-- server/package.json | 24 ++----- server/src/.mf.config.SAMPLE.json | 9 --- server/src/commandLine.mjs | 1 - server/test/suite/config.test.mjs | 7 -- server/test/suite/sdkManagement.test.mjs | 4 +- 20 files changed, 153 insertions(+), 121 deletions(-) create mode 100644 docs/Versioning.md delete mode 100644 package-lock.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 8cf59dbc..45665da1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,29 @@ -# Release Notes +# Change Log -## 0.1.1 +All notable changes to this project will be documented in this file. -- Initial creation +## [1.0.1] - 2023-10-18 + +### Added + +* Introduced official versioning for the application. + +### Changed + +* The application now starts using the command `npm start` as opposed to the previously used `npm run dev`. +* Refactored script commands in `server/package.json` for better clarity and organization. +* Eliminated `firebolt-discovery-openrpc` as an optional dependency. It will no longer be utilized in the application. +* Deleted `package-lock.json` from the root directory. +* Updated documentation for greater clarity and accuracy. + +### Fixed + +## [0.1.1] - 2022-02-16 + +### Added + +* Initial creation of the application. + +### Changed + +### Fixed \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index 5a5d98fe..776e35ae 100644 --- a/Dockerfile +++ b/Dockerfile @@ -40,5 +40,5 @@ ENV PATH=${PATH}:/usr/src/firebolt/mock-firebolt/cli WORKDIR /usr/src/firebolt/mock-firebolt/server ENTRYPOINT [ "npm", "run", "start" ] -# By default, core/manage OpenRPC retrieved from HTTP is enabled. When using 'docker run', users can pass --discovery as command-line parameters +# By default, core/manage OpenRPC retrieved from HTTP is enabled. CMD [ ] \ No newline at end of file diff --git a/README.md b/README.md index 0d01c09c..797ba7e4 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Note, too, that since the SDK does not validate parameters on method calls, app - Controllable Mock Firebolt server (NodeJS websocket + HTTP server) - Control mock method responses via control plane RESTful API, CLI, web admin UI (soon), browser extension (soon) - 100% OpenRPC-driven; no SDK-specific details within the implementation -- Supports Firebolt SDKs: **core** (always), **manage** (always), **discovery** (optional) +- Supports Firebolt SDKs: **core** & **manage** - Complete documentation - Docker support - Validation (based on OpenRPC specifications) of all parameters sent on method calls @@ -87,10 +87,7 @@ The next two sections presume you are using the out-of-the-box `.mf.config.json` # Firebolt SDK Support -Mock Firebolt supports these Firebolt SDKs: **core**, **manage**, **discovery**. - -For developers building "operator apps" / "search and discover apps" which need one or more of these SDKs, when running the Mock Firebolt server, you can pass flags like `--discovery` to enable the specific SDK desired. Note of course that ultimately, when running on a real device, your app will only have whatever permissions it has been given. - +Mock Firebolt supports these Firebolt SDKs: **core** & **manage**. # $badger Support @@ -121,23 +118,18 @@ npm install # If you want support for Firebolt Core/Manage SDK # Run in a separate terminal window/tab, or use '&' to background -npm run dev - -# If you want support for the Firebolt Discovery SDK -# Include the flag(s) you require -# Note the extra double dash! -npm run dev -- --discovery +npm start # If you need to use non-standard ports for any reason: -npm run dev -- --httpPort 3456 --socketPort 9876 --wsSessionServerPort 1234 +npm start -- --httpPort 3456 --socketPort 9876 --wsSessionServerPort 1234 #If you wish to enable conduit functionality* -npm run dev -- --conduit +npm start -- --conduit *Note*: Requires Conduit to be running. See the Conduit documentation (./conduit/README.md) for more information. # If you need to use proxy connection for any reason: -npm run dev -- --proxy : +npm start -- --proxy : Refer more about proxy mode in ./docs/ProxyMode.md # To use the control CLI (assuming you're in the top-level directory for this repo) @@ -153,8 +145,7 @@ Click the "Load Unpacked" button (top left corner of browser window) Navigate to the directory under browser-extensions which contains a manifest.json file and click "Select" ``` -Now you can access core/manage OpenRPC from HTTP by adding `"url": "https://rdkcentral.github.io/firebolt/requirements/latest/specifications/firebolt-open-rpc.json"` in mf.config.SAMPLE.json and copying to mf.config.json and can add `@firebolt-js/discovery-sdk` in your app's `package.json` file, import `@firebolt-js/discovery-sdk` optionally in your code in case to make discovery calls - +Now you can access core/manage OpenRPC from HTTP by adding `"url": "https://rdkcentral.github.io/firebolt/requirements/latest/specifications/firebolt-open-rpc.json"` in `mf.config.SAMPLE.json` and copying to `mf.config.json`. # Usage (via Docker, if you prefer) @@ -182,14 +173,6 @@ docker run -d \ -p 9998:9998 \ $MF_DOCKER_USER/mock-firebolt -# Run the image, enabling the discovery SDK (not typical) -docker run -d \ - --name mf \ - --mount type=bind,source="$(pwd)",target=/usr/src/firebolt/host-files \ - -p 3333:3333 \ - -p 9998:9998 \ - $MF_DOCKER_USER/mock-firebolt -- --discovery - # Get container ID docker ps | grep mf diff --git a/conduit/package-lock.json b/conduit/package-lock.json index 618fc5d4..5aef6c46 100644 --- a/conduit/package-lock.json +++ b/conduit/package-lock.json @@ -1,11 +1,11 @@ { - "name": "Conduit", + "name": "conduit", "version": "1.0.1", "lockfileVersion": 2, "requires": true, "packages": { "": { - "name": "Conduit", + "name": "conduit", "version": "1.0.1", "license": "Apache 2.0", "dependencies": { @@ -21,9 +21,6 @@ "style-loader": "^3.3.1", "webpack": "^5.68.0", "webpack-cli": "^4.9.2" - }, - "optionalDependencies": { - "@firebolt-js/discovery-sdk": "0.1.0-alpha.2" } }, "node_modules/@discoveryjs/json-ext": { @@ -35,12 +32,6 @@ "node": ">=10.0.0" } }, - "node_modules/@firebolt-js/discovery-sdk": { - "version": "0.1.0-alpha.2", - "resolved": "https://registry.npmjs.org/@firebolt-js/discovery-sdk/-/discovery-sdk-0.1.0-alpha.2.tgz", - "integrity": "sha512-OMODHtwJ6beED9tQsSJdjbhxp6XCJdz6PAHKhM+ljFIiPjFUOuRCORkcKr1UKIxkYrB/Lynv0q2UoER80jQUng==", - "optional": true - }, "node_modules/@firebolt-js/sdk": { "version": "0.6.0", "resolved": "https://registry.npmjs.org/@firebolt-js/sdk/-/sdk-0.6.0.tgz", @@ -3239,12 +3230,6 @@ "integrity": "sha512-ws57AidsDvREKrZKYffXddNkyaF14iHNHm8VQnZH6t99E8gczjNN0GpvcGny0imC80yQ0tHz1xVUKk/KFQSUyA==", "dev": true }, - "@firebolt-js/discovery-sdk": { - "version": "0.1.0-alpha.2", - "resolved": "https://registry.npmjs.org/@firebolt-js/discovery-sdk/-/discovery-sdk-0.1.0-alpha.2.tgz", - "integrity": "sha512-OMODHtwJ6beED9tQsSJdjbhxp6XCJdz6PAHKhM+ljFIiPjFUOuRCORkcKr1UKIxkYrB/Lynv0q2UoER80jQUng==", - "optional": true - }, "@firebolt-js/sdk": { "version": "0.6.0", "resolved": "https://registry.npmjs.org/@firebolt-js/sdk/-/sdk-0.6.0.tgz", @@ -5622,4 +5607,4 @@ "dev": true } } -} \ No newline at end of file +} diff --git a/conduit/package.json b/conduit/package.json index 1d0ecddd..bced9b45 100644 --- a/conduit/package.json +++ b/conduit/package.json @@ -1,5 +1,5 @@ { - "name": "Conduit", + "name": "conduit", "description": "A TV app that works in concert with Mock Firebolt in Reverse Proxy mode", "version": "1.0.1", "private": true, @@ -16,9 +16,6 @@ "@firebolt-js/sdk": "^0.6.0", "json": "^11.0.0" }, - "optionalDependencies": { - "@firebolt-js/discovery-sdk": "0.1.0-alpha.2" - }, "devDependencies": { "copy-webpack-plugin": "^11.0.0", "css-loader": "^6.6.0", diff --git a/docs/DotConfig.md b/docs/DotConfig.md index eb60e394..f46bcddb 100644 --- a/docs/DotConfig.md +++ b/docs/DotConfig.md @@ -2,20 +2,15 @@ Mock Firebolt: mf.config.json(Supported SDK's) ======================= ## Supported SDK's -Mock Firebolt supports these Firebolt SDKs: **core** (always), **manage** (always), **discovery** (optional) -mf.config.json file contains a list of OpenRPC/SDK's supported by Mock Firebolt, out of which core/manage OpenRPC is supported by default and `discovery` is optional. -and it contains associated command-line flags you provide when you start the server. -# If you're only using the Firebolt Core/Manage OpenRPC +Mock Firebolt supports these Firebolt SDKs: **core** & **manage**. + +The `mf.config.json` file contains a list of OpenRPC/SDK's supported by Mock Firebolt, out of which core/manage OpenRPC is supported by default. + +# Starting Mock Firebolt Run Mock Firebolt server as: -``` -npm run dev -``` -# If you want support for the Firebolt Discovery SDK -# Include the flag you require -# Note the extra double dash! ``` -npm run dev -- --discovery +npm start ``` Out of the box, Mock Firebolt contains a .mf.config.SAMPLE.json file. You should copy this file to .mf.config.json (in the same directory) and then make any changes to the new file. @@ -44,5 +39,5 @@ By default, Mock Firebolt will validate incoming method names and parameters and Example: ``` cd server -npm run dev -- --novalidate method --novalidate response +npm start -- --novalidate method --novalidate response ``` diff --git a/docs/Overview.md b/docs/Overview.md index c0a2ac3b..55bbbe25 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -170,13 +170,13 @@ node cli.mjs --sequence ../examples/device-onDeviceNameChanged.sequence.json See `server/src/triggers/lifecycle.ready/post.mjs`, etc. -Run Mock Firebolt like: `npm run dev -- --triggers ./src/triggers` +Run Mock Firebolt like: `npm start -- --triggers ./src/triggers` #### novalidate Flag By default, Mock Firebolt will validate incoming method names and parameters and outgoing events. If you want to prevent some or all of these validation checks, you must either set the value of validate in mf.config.json to a subset of the default values (["method", "params", "response", "event"]) or pass one or more --novalidate command line arguments when you start Mock Firebolt. -Run Mock Firebolt like: `npm run dev -- --novalidate response --novalidate params` +Run Mock Firebolt like: `npm start -- --novalidate response --novalidate params` ### Web Admin UI ``` diff --git a/docs/ProxyMode.md b/docs/ProxyMode.md index a4dc470b..8aeac904 100644 --- a/docs/ProxyMode.md +++ b/docs/ProxyMode.md @@ -18,7 +18,7 @@ When Mock Firebolt starts up, it will check for `--proxy` in command line argume # Usage If you need to use proxy connection for any reason: -```npm run dev -- --proxy 192.168.0.100:9998``` +```npm start -- --proxy 192.168.0.100:9998``` Default port will be 9998 if not passed expliclity. diff --git a/docs/Triggers.md b/docs/Triggers.md index 54e91012..11cfc711 100644 --- a/docs/Triggers.md +++ b/docs/Triggers.md @@ -42,7 +42,7 @@ To enable triggers, you must provide one or more directories which contain trigg Example: ``` cd server -npm run dev -- --triggers ./src/triggers --triggers /some/other/dir/with/triggers +npm start -- --triggers ./src/triggers --triggers /some/other/dir/with/triggers ``` As shown in the example above, you may load triggers from multiple directories. This allows you to organize your triggers as you see fit, and load subsets of them when you start Mock Firebolt. diff --git a/docs/Versioning.md b/docs/Versioning.md new file mode 100644 index 00000000..97439632 --- /dev/null +++ b/docs/Versioning.md @@ -0,0 +1,90 @@ +# Versioning Guidelines for Mock Firebolt + +This document outlines the guidelines we follow for versioning Mock Firebolt. Our aim is to ensure clarity, consistency, and predictability in our releases, making it easier for both developers and users to understand the state and stability of the software. + +## Versioning + +We use [semantic versioning](https://semver.org/) which uses the `MAJOR.MINOR.PATCH` format: + +* **MAJOR** version for incompatible changes that require user intervention. + +* **MINOR** version for backward-compatible new features and enhancements. + +* **PATCH** version for backward-compatible bug fixes. + +## When to Cut a New Version + +1. **Major Releases:** + + * Breaking changes have been introduced. + + * Major rewrites or architectural changes have been completed. + + * When significant features that might affect the application's overall behavior are added. + +2. **Minor Releases:** + + * New, backward-compatible functionality has been added. + + * Deprecated functions or features are marked (to be removed in the next major version). + + * Performance enhancements or sizable improvements that don't disrupt existing functionality. + +3. **Patch Releases:** + + * Backward-compatible bug fixes. + + * Minor updates that resolve issues affecting the stability of the application. + +4. **Documentation Changes:** + * Minor documentation changes do no necessitate a new version. + + * Significant documentation overhauls, especially those reflecting changes in the software's behavior or features, should accompany a minor or major release. + +## Changelog Maintenance + +With every new version, a corresponding update should be made to [CHANGELOG.md](../CHANGELOG.md). + +* Clearly specify the version number. + +* Enumerate all changes, categorized by "Added", "Changed", and "Fixed". + +* Provide a brief description of each change. + +Use the following template to update the Change Log: + +``` +## [Unreleased] - yyyy-mm-dd + +### Added + +### Changed + +### Fixed + +``` + + +## Steps to Create a New Version + +1. Update the `package.json` files with the new version number you intend to release. This ensures that the project's metadata accurately reflects the current version. + +2. Update [CHANGELOG.md](../CHANGELOG.md) with the details of the release. + +3. Navigate to the [tags section](https://github.com/rdkcentral/mock-firebolt/tags) of the `mock-firebolt` repository on GitHub. + +4. Click on the "Create a new release" button. + +5. In the "Choose a tag" dropdown, the default action is set to "Create a new tag on publish". If you leave the dropdown as-is, it will automatically create a new tag using the release name. + +6. Keep the release target to be the `main` branch. + +7. For "Release title", you can use the same version number of the release. + +8. In the description box, provide a brief summary of the changes or simply reference your updated `CHANGELOG.md`. + +9. If you have any binaries, assets, or additional files to distribute with this release, attach them in the "Attach binaries by dropping them here or selecting them" section. + +10. Once everything looks good, click on the "Publish release" button. + +11. Notify the team and users (if applicable) of the new release. diff --git a/functional/package-lock.json b/functional/package-lock.json index 8114a15b..e6340b6f 100644 --- a/functional/package-lock.json +++ b/functional/package-lock.json @@ -1,12 +1,12 @@ { "name": "@firebolt-js/mock-firebolt-functional-tests", - "version": "0.0.1", + "version": "1.0.1", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@firebolt-js/mock-firebolt-functional-tests", - "version": "0.0.1", + "version": "1.0.1", "license": "Apache-2.0", "dependencies": { "axios": "^0.24.0", diff --git a/functional/package.json b/functional/package.json index 81cd7f90..19e07ac8 100644 --- a/functional/package.json +++ b/functional/package.json @@ -1,6 +1,6 @@ { "name": "@firebolt-js/mock-firebolt-functional-tests", - "version": "0.0.1", + "version": "1.0.1", "description": "Command-line interface for controlling the Mock Firebolt server", "scripts": { "test": "NODE_ENV=test npx jest --config=jest.config.js --silent -i", diff --git a/functional/tests/utilities.mjs b/functional/tests/utilities.mjs index b9d24405..fbb4ca43 100644 --- a/functional/tests/utilities.mjs +++ b/functional/tests/utilities.mjs @@ -23,7 +23,7 @@ import WebSocket from "ws"; import path from "path"; let mfProcess; -let startMf = "npm run dev"; +let startMf = "npm start"; const mfStarted = "Listening on HTTP port"; const mfHost = "localhost"; const mfUserHeader = "x-mockfirebolt-userid"; diff --git a/package-lock.json b/package-lock.json deleted file mode 100644 index 56ad6209..00000000 --- a/package-lock.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "name": "mock-firebolt", - "lockfileVersion": 2, - "requires": true, - "packages": {} -} diff --git a/server/README.md b/server/README.md index 86fb56ba..95ad2cfb 100644 --- a/server/README.md +++ b/server/README.md @@ -24,8 +24,6 @@ curl --location --request GET 'http://localhost:3333/api/v1/healthcheck' "mockFirebolt": "", "sdk" "core": "", - "discovery": "", - } } } ``` @@ -61,13 +59,10 @@ curl --location --request GET 'http://localhost:3333/api/v1/meta' { }, ... ] }, - "discovery": { - // Included if --discovery was provided when Mock Firebolt server was started - } + } +} ``` - - ## Get all OpenRPC metadata with all $refs replaced in-line (handy for debugging) ### cURL Command: diff --git a/server/package.json b/server/package.json index 1b900b33..a28f1efc 100644 --- a/server/package.json +++ b/server/package.json @@ -1,26 +1,15 @@ { "name": "@firebolt-js/mock-firebolt", - "version": "2.0.1", + "version": "1.0.1", "description": "Controllable mock Firebolt server", "main": "./build/index.mjs", "scripts": { "clean": "node ./scripts/clean.mjs", - "prepare:setup": "npm run clean", - "build:discovery": "node ./scripts/copy.mjs ./node_modules/@firebolt-js/discovery-sdk/dist/firebolt-discovery-open-rpc.json ./build/firebolt-discovery-open-rpc.json", - "build:openrpc:NOTES": "Only use if you are using all three Firebolt SDKs", - "build:openrpc": "npm run build:discovery", - "build:mf": "node ./scripts/rcopy.mjs ./src ./build && node ./scripts/copy.mjs ./src/.mf.config.json ./build/.mf.config.json && node ./scripts/copy.mjs ./package.json ./build/package.json", - "build:NOTES": "Only use if you are using all three Firebolt SDKs", - "build": "npm run build:openrpc && npm run build:mf", + "build": "node ./scripts/rcopy.mjs ./src ./build && node ./scripts/copy.mjs ./src/.mf.config.json ./build/.mf.config.json && node ./scripts/copy.mjs ./package.json ./build/package.json", "test": "NODE_OPTIONS=--experimental-vm-modules NODE_ENV=test npx jest --config=jest.config.js --detectOpenHandles --runInBand --forceExit", - "start:NOTES1": "Can do 'npm run start' (core/manage OpenRPC only) or 'npm run start -- --discovery'", - "start": "node build/index.mjs", - "dev:NOTES1": "Typical developer script once 'npm run build:openrpc' has been executed once", - "dev:NOTES2": "Can do 'npm run dev' (core/manage OpenRPC only) or 'npm run dev -- --discovery'", - "dev": "npm run build:mf && npm run start --", - "upgradeSDKAndBuildMF": "npm update @firebolt-js/discovery-sdk && npm run clean && npm run build:discovery && npm run build:mf", - "postinstall": "npm run upgradeSDKAndBuildMF" - }, + "start": "npm run build && node build/index.mjs", + "dev": "echo 'WARNING: \"npm run dev\" is DEPRECATED and may be removed in a future release. Use \"npm start\" instead.' && npm start" + }, "repository": { "type": "git", "url": "git+https://github.com/rdkcentral/mock-firebolt.git" @@ -59,9 +48,6 @@ "uuid": "^8.3.2", "ws": "^8.2.3" }, - "optionalDependencies": { - "@firebolt-js/discovery-sdk": "git+https://github.com/rdkcentral/firebolt-discovery-sdk.git" - }, "keywords": [ "firebolt", "mock" diff --git a/server/src/.mf.config.SAMPLE.json b/server/src/.mf.config.SAMPLE.json index df67e5d5..79c5ff85 100644 --- a/server/src/.mf.config.SAMPLE.json +++ b/server/src/.mf.config.SAMPLE.json @@ -13,15 +13,6 @@ "url": "https://rdkcentral.github.io/firebolt/requirements/latest/specifications/firebolt-open-rpc.json", "enabled": true }, - - { - "name": "discovery", - "cliFlag": "discovery", - "cliShortFlag": "d", - "fileName": "firebolt-discovery-open-rpc.json", - "enabled": false - }, - { "name": "mock", "cliFlag": "mock", diff --git a/server/src/commandLine.mjs b/server/src/commandLine.mjs index fae692a0..98c4b53b 100644 --- a/server/src/commandLine.mjs +++ b/server/src/commandLine.mjs @@ -33,7 +33,6 @@ import { mergeArrayOfStrings } from './util.mjs'; // node index.mjs --conduitKeySocketPort 9986 ... (Use custom socket port for forwarding key presses over Conduit (default: 9996)) // node index.mjs --developerToolPort 9985 ... (Use custom socket port for developer tool port (default: 9995)) // node index.mjs --developerToolName "My MF" ... (Use custom developer tool name (default: "Mock Firebolt")) -// node index.mjs -- --discovery ... (core/manage OpenRPC + discovery SDK) // node index.mjs --triggers --triggers (Load triggers from files in these paths) // node index.mjs --novalidate --novalidate (does not validate options provided by user) diff --git a/server/test/suite/config.test.mjs b/server/test/suite/config.test.mjs index 47b0bf8d..a8d23f01 100644 --- a/server/test/suite/config.test.mjs +++ b/server/test/suite/config.test.mjs @@ -51,13 +51,6 @@ test(`config works properly`, () => { url: "https://rdkcentral.github.io/firebolt/requirements/latest/specifications/firebolt-open-rpc.json", name: "core", }, - { - cliFlag: "discovery", - cliShortFlag: "d", - enabled: false, - fileName: "firebolt-discovery-open-rpc.json", - name: "discovery", - }, { name: "mock", cliFlag: "mock", diff --git a/server/test/suite/sdkManagement.test.mjs b/server/test/suite/sdkManagement.test.mjs index bf0e3326..a1dbe8ef 100644 --- a/server/test/suite/sdkManagement.test.mjs +++ b/server/test/suite/sdkManagement.test.mjs @@ -36,8 +36,8 @@ test(`sdkManagement works properly`, () => { }); test(`sdkManagement works properly with given name is enabled via a command-line flag`, () => { - commandLine.enabledSdkNames.push("discovery"); - const result = sdkManagement.isSdkEnabled("discovery"); + commandLine.enabledSdkNames.push("updatedSdk"); + const result = sdkManagement.isSdkEnabled("updatedSdk"); expect(result).toBe(true); commandLine.enabledSdkNames.pop(); });