Skip to main content

How to contribute to xpm

license GitHub issues GitHub pulls JavaScript Style Guide

This page is designed for developers who plan to contribute new features or fix bugs in the xPack Project Manager project and provides documentation on how to build and test the package.

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

Prerequisites​

xpm is a portable Node.js module; development can be performed on macOS, GNU/Linux and even Windows (although some npm scripts must be executed in a Git Bash terminal).

The prerequisites are:

  • git
  • node >= 18.0.0
  • npm

To ensure compatibility with older node, preferably revert to an older one:

nvm use --lts 18
code

Get project sources​

The project is hosted on GitHub:

The project uses multiple branches:

  • master, with the latest stable version (default)
  • development, with the current development version
  • website, with the current content of the website; pushes to this branch automatically trigger publishes the main website
  • webpreview, with the current content of the preview website; pushes to this branch automatically trigger publishes the preview website

To clone the stable branch (master), run the following commands in a terminal (on Windows use the Git Bash console):

mkdir ~/Work/npm-packages && cd ~/Work/npm-packages
git clone https://github.com/xpack/xpm-js.git xpm-js.git

For development purposes, clone the development branch:

mkdir ~/Work/npm-packages && cd ~/Work/npm-packages
git clone \
  --branch development \
  https://github.com/xpack/xpm-js.git xpm-js.git

Or, if the repo was already cloned:

git -C ~/Work/npm-packages/xpm-js.git pull
tip

To contribute Pull Requests, fork the project and be sure the Copy the master branch only is disabled.

Use the xpack-development branch and be sure you contribute the Pull Requests back to the xpack-development branch.

Satisfy dependencies​

npm install

To facilitate the use of this module in other packages, add a link from the central npm storage to this local development folder:

npm link

And in the projects referring it:

npm link xpm

Start the compile background task​

The TypeScript compiler can automatically recompile modified files. For this, start it in watch mode.

npm run compile-watch

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.

For spacial cases, it is possible to configure/disable some rules.

/* eslint-disable-next-line no-xxx-yyy */

The known rules are documented in the eslint project.

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.20.8 fix
> standard --fix test
...

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.

Tests​

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

Tests can be written in TypeScript, assuming ts-node is also installed.

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

npm install
npm run test

A typical test result looks like:

% npm run test

> xpm@undefined test
> npm run lint && npm run test-tap -s


> xpm@undefined lint
> standard

tests/tap/120-utils-global-config.js .................. 1/1 1s
tests/tap/130-utils-spawn.js .......................... 1/1 924ms
tests/tap/140-utils-xpack.js .......................... 2/2 1s


...

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

% npm run tap tests/tap/010-xxx.ts

...

Continuous Integration (CI)​

The module is CI tested on every push via GitHub Actions, on Ubuntu, Windows and macOS, using node 18, 20 and 22.