Skip to content

Latest commit

 

History

History
230 lines (157 loc) · 6.21 KB

README-DEVELOPER.md

File metadata and controls

230 lines (157 loc) · 6.21 KB
Raw

npm (scoped) license Standard CI on Push GitHub issues GitHub pulls

Developer info

This page documents the prerequisites and procedures used during the development of the xpm module.

This project is currently written in JavaScript, but a rewrite to TypeScript is planned.

Prerequisites

The prerequisites are:

  • git
  • node >= 14.13.1 (for stable modules)
  • npm

Clone the project repository

The project is hosted on GitHub:

To clone the master branch, use:

mkdir "${HOME}/Work/node-modules" && cd "${HOME}/Work/node-modules"
git clone https://github.com/xpack/xpm-js.git xpm-js.git

For development, to clone the develop branch, use:

git clone --branch develop https://github.com/xpack/xpm-js.git xpm-js.git

Satisfy dependencies

npm install

To later check for newer dependencies:

npm outdated

Details about dependencies:

Language standard compliance

The module uses ECMAScript 6 class definitions and modules.

Standard style

As style, the project uses the JavaScript Standard Style, automatically checked at each commit via CI.

Generally, to fit two editor windows side by side in a screen, all files should limit the line length to 80.

/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */

Known and accepted exceptions:

  • none

To manually fix compliance with the style guide (where possible):

$ npm run fix

> xpm@0.16.2 fix
> standard --fix

Tests

The tests use the node-tap framework (A Test-Anything-Protocol library for Node.js, written by Isaac Schlueter).

As for any npm package, the standard way to run the project tests is via npm test:

cd xpm-js.git
npm install
npm run test

To run a specific test with more verbose output, use npm run tap:

npm run tap test/tap/...

Coverage tests

Coverage tests are a good indication on how much of the source files is exercised by the tests. Ideally all source files should be covered 100%, for all 4 criteria (statements, branches, functions, lines).

To run the coverage tests, use npm run test-coverage:

npm run test-coverage
...

Coverage exceptions

Use /* istanbul ignore next <something> */ before the code to be ignored (https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md).

Fully excluded files:

  • lib/utils/cmd-shim.js

Continuous Integration (CI)

The continuous integration tests are performed via GitHub Actions.

The tests are currently performed with node 14, 16, 18.

To preserve compatibility with Node 10, use the older version of the documentation:

Documentation metadata

The documentation metadata follows the JSdoc tags.

To enforce checking at file level, add the following comments right after the use strict:

'use strict'
/* eslint valid-jsdoc: "error" */
/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */

Note: be sure C style comments are used, C++ styles are not parsed by ESLint.

Dependencies issues

There were some problems with cacache & pacote.

  • cacache@15.0.3: fails to download binaries.
  • pacote@11.1.10: apparently works, but passing the stream to cacache fails.

The previous known to work versions:

    "cacache": "^12.0.2",
    "pacote": "^9.4.1",

Note: the cacache version should match the one used inside pacote.

TODO: investigate and update.

Project templates

xpm is able to create new projects based on templates.

To be accepted as a template, a project must:

  • be an xPack (have a package.json which includes an xpack property
  • have a property called main in package.json, pointing to a JavaScript file that can be consumed by await import() (formerly require())
  • the main file must export a class called XpmInitTemplate
  • an instances of this class must have a run() method.
  • have all dependencies bundled in (via bundleDependencies)

The steps invoked by xpm to initialise a project from a template are:

  • call pacote to install the xPack in the global home folder
  • identify the main property in package.json
  • import the XpmInitTemplate class from the main JavaScript file by invoking require()
  • instantiate the XpmInitTemplate class
  • execute the run() method.

The full code is in init.js, but a simplified version looks like this:

    await pacote.extract(config.template, globalPackagePath,
      { cache: cacheFolderPath })

    const mainTemplatePath = path.join(globalPackagePath, globalJson.main)

    context.CliError = CliError
    context.CliExitCodes = CliExitCodes

    const { XpmInitTemplate } = await import(mainTemplatePath)
    const xpmInitTemplate = new XpmInitTemplate(context)
    const code = await xpmInitTemplate.run()