Skip to main content

How to contribute to xpm

GitHub package.json version NPM Version license GitHub issues GitHub pulls CI on Push JavaScript Style Guide license

This page is designed for developers who intend to contribute new features or resolve bugs within the xPack Project Manager project and provides documentation on building and testing the package.

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

Prerequisites​

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

The prerequisites are:

  • git
  • node >= 20.0.0
  • npm

To ensure compatibility with older node versions, it is preferable to revert to an older one:

nvm use --lts 20
code

Obtain project sources​

The project is hosted on GitHub:

Branches

This project utilises multiple branches:

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

All development is conducted in the development branch, and contributions via Pull Requests should be directed to this branch.

When new releases are published, the development branch is merged into master.

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

rm -rf ~/Work/xpack/xpm-js.git && \
mkdir -p ~/Work/xpack && \
git clone \
  --branch master \
  https://github.com/xpack/xpm-js.git \
  ~/Work/xpack/xpm-js.git
For development purposes, clone the development branch.
rm -rf ~/Work/xpack/xpm-js.git && \
mkdir -p ~/Work/xpack && \
git clone \
  --branch development \
  https://github.com/xpack/xpm-js.git \
  ~/Work/xpack/xpm-js.git

Alternatively, if the repository has already been cloned:

git -C ~/Work/xpack/xpm-js.git pull
tip

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

Utilise the development branch and ensure you contribute the Pull Requests back to the development branch.

During development, it is convenient to maintain a writable instance of the source code to enable changes in parallel with the parent project.

To facilitate the use of a writable instance of this source code in other projects, add a link from the user's global npm store to this local development folder:

npm --prefix ~/Work/xpack/xpm-js.git link

And in the projects referring it:

npm link xpm

Satisfy dependencies​

npm install

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

Documentation metadata​

The documentation metadata follows the JSdoc tags.

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

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

Note: ensure C style comments are used, as C++ styles are not parsed by ESLint.

Tests​

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

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

As with any npm package, the standard method to execute 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 subject to CI testing on every push via GitHub Actions, on Ubuntu, Windows and macOS, utilising node 18, 20 and 22.