Skip to content

Latest commit

 

History

History
232 lines (160 loc) · 9.5 KB

DeveloperGuide.md

File metadata and controls

232 lines (160 loc) · 9.5 KB

ecu.test diff extension developer documentation

Description

Please have a look at section 'Description' inside README.md.

Features

Please have a look at section 'Features' inside README.md.

Fork information

This project is based on the boilerplate Chrome Extension Webpack from Sebastian Szczepański.

Prerequisites

Install node.js

First, you have to install node.js to have access to the package manager npm for building the browser extension.

Development Setup

Install dependencies

Open the ecu.test diff project in your IDE of choice and run the following terminal command to install the dependencies including typescript:

npm install -g typescript

Build process

If you want to build the ecu.test diff extension locally for development purposes or for production use, you have access to different scripts:

Note: All of these scripts can be found and modified within the ./package.json of the project.

Firefox:

npm run start:firefox
npm run build:firefox

Chrome/Edge:

npm run start:chrome
npm run build:chrome

Your compiled files are available inside the ./dist folder after the build process. Note: Since the build folder is ./dist, only the last build execution is present.

Integration

You can integrate and test the local extension in your browsers:

  • To load the local extension you need required rights (probably managed by your IT department). The browser will probably inform you if you are not allowed to contents apart from the official stores.
  • In Chrome/Edge you can load the extension on the extensions page. The slider Developer mode on the upper right has to be activated. Then, you can click on the button Load unpacked and select the ./dist folder.
  • In Firefox, you can load the extension on the debugging page (follow this link or click on 'debug add-ons' when managing addons). Click on the button Load Temporary Add-on and select a typical file in ./dist folder, e.g. ./dist/manifest.json.

Testing / Linting / Code formatting

For these purposes, there are three additional scripts that execute the local tests, start the linter in the source code and do some code formatting:

Prettier

Prettier is a code formatter that enforces a consistent style by parsing your code and re-printing it. Select the files you want to format and run the following command:

# check all files
npm run prettier:check

# fix findings for all files
npm run prettier:write .

# fix finding for specific files
npm run prettier:write ./<your_file>

Linting

Use the internal npm linter with the following command:

npm run lint

Testing

Your defined tests can be run with the command blow. The command runs all tests defined in the root 'test' folder and generates a coverage report.

npm run test

Continuous Integration and Deployment

All CI/CD workflows are located in .github/workflows

name on output artifacts
deploy tag - -
build
  • push and pr to main
  • workflow dispatch
  • reused by deploy workflow
- chrome and firefox build
test reused by build workflow test result -
reuse
  • push and pr to main
  • workflow dispatch
 spdx sbom sbom.spdx

Those workflows are running automatically after having some changes to the remote repository.

Build

The project can be built using the CI or locally running the corresponding npm command

# chrome
npm run build:chrome

# firefox
npm run build:firefox

When running the build process via GitHub action, it will provide a build artifact for each browser (firefox/chrome).

Deployment

To publish a new release see the following workflow. All changes will be done on main branch:

  • increase the extension version tag within the manifest file
    • version schema -> <major>.<minor>.<patch>.<beta>
    • upgrade the version tag for a release by deleting the beta version flag to ..
    • increase the specific version
      old new
      <major>.<minor>.<patch> <major>.<minor>.<patch+1>
      <major>.<minor>.<patch> <major>.<minor+1>.0
      <major>.<minor>.<patch> <major+1>.0.0
  • commit with Prepare release version <release.version>
  • create next tag for latest commit -> ecu-test-diff-[0-9]+.[0-9]+.[0-9]+
  • push changes & the created tag
  • create new release from existing tag after all checks are successful
  • increase the extension version tag within the manifest file for next beta version
    • <released.version> -> <released.version>.0
  • commit with Prepare for next development cycle and push

See the following store-specific information, to handle release specification individually (if needed)

Chrome Web Store

  • a Google Chrome developer account is required
  • any secrets that are necessary for the publication process are set as Actions secret
  • any additional information, see Publish in the Chrome Web Store
  • after publishing the application, a review is mostly outstanding and will be published automatically afterward

Firefox Add-ons

  • a mozilla developer account is required

  • any secrets that are necessary for the publication process are set as Actions secret

  • any additional information, see Submitting an add-on

    • Note:

      • The tool web-ext (from mozilla) will help you in the signing process which is required for the use of add-ons without a debug-mode in firefox.

        For example, install it globally.

        npm install web-ext -g
cd ./dist
web-ext build

  • after publishing the application, a review is usually pending and will be published afterward

    • Note:
      • the add-on may be subject to additional review.
      • you will receive a notification about the outcome of the review at a later time.

Open-Source Software compliance

reuse

To ensure open-source difference with our provided software at tracetronic GmbH, we use the tool reuse. After installing the tooling in your local environment, you can check for open-source compliance with:

reuse lint

If you want to add the SPDX-Headers automatically - in case there are a lot of files - you can do this with the following:

reuse annotate --copyright="tracetronic GmbH" --license=MIT -r <your_folder>/ ./<your_file>.ts

Licensing

This work is licensed under MIT license. You can find the original license text from the forked project inside LICENSE.original.

Cyclonedx

To generate a software bill of material (sbom) for the project, run from your terminal root folder:

#skip if you have cyclonedx already installed globally
npm install --global @cyclonedx/cyclonedx-npm

cyclonedx-npm --output-format json --output-file bom.json

#uninstall cyclonedx if desired
npm uninstall --global @cyclonedx/cyclonedx-npm

The generated sbom destination is ./bom.json.