The project is hosted on GitHub:
The project uses two branches:
master, with the latest stable version (default)develop, with the current development version
To clone the master branch, use:
mkdir ${HOME}/Work/npm-packages && cd ${HOME}/Work/npm-packages
git clone \
https://github.com/xpack/xpm-liquid-ts.git xpm-liquid-ts.gitFor development, to clone the develop branch, use:
git clone --branch develop \
https://github.com/xpack/xpm-liquid-ts.git xpm-liquid-ts.gitThe prerequisites are:
- node >= 18.0.0
- npm
To ensure compatibility with older node, revert to an older one:
nvm use --lts 18
codenpm installcd xpm-liquid-ts.git
npm linkAnd in the projects referring it:
npm link @xpack/xpm-liquidThe TypeScript compiler can automatically recompile modified files. For
this, start it in watch mode.
npm run compile-watchThe current version is TypeScript 4:
The compiler is configured to produce es2020 & commonjs files,
which means ECMAScript6 with legacy CommonJS modules, that can be imported
by any other project either via require() or import.
For more details on how to configure tsconfig.json, please see:
As style, the project uses ts-standard, the TypeScript variant of
Standard Style,
automatically checked at each commit via CI.
// eslint-disable-next-line @typescript-eslint/no-xxx-yyyThe known rules are documented in the typescript-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
> @xpack/[email protected] fix
> ts-standard --fix src && standard --fix test
...The documentation metadata uses the TypeDoc tags, without explicit types, since they are provided by TypeScript.
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
(https://node-tap.org/docs/using-with/#using-tap-with-typescript)
As for any npm package, the standard way to run the project tests is via
npm run test:
cd xpm-liquid-ts.git
npm install
npm run testA typical test result looks like:
% npm run test-100-c8
> @xpack/[email protected] pretest-100-c8 /Users/ilg/My Files/WKS Projects/xpack.github/npm-packages/xpm-liquid-ts.git
> npm run lint
> @xpack/[email protected] lint /Users/ilg/My Files/WKS Projects/xpack.github/npm-packages/xpm-liquid-ts.git
> ts-standard src && standard esm
> @xpack/[email protected] test-100-c8 /Users/ilg/My Files/WKS Projects/xpack.github/npm-packages/xpm-liquid-ts.git
> npm run test-tap-coverage-100-c8 -s
(node:32915) ExperimentalWarning: --experimental-loader is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
(node:32914) ExperimentalWarning: --experimental-loader is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
(node:32916) ExperimentalWarning: --experimental-loader is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
tests/tap/010-functions.ts ............................ 8/8
tests/tap/020-map.ts ................................ 26/26
tests/tap/030-substitutions.ts ...................... 24/24
total ............................................... 58/58
58 passing (2s)
ok
----------------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------------|---------|----------|---------|---------|-------------------
All files | 100 | 100 | 100 | 100 |
src | 100 | 100 | 100 | 100 |
index.ts | 100 | 100 | 100 | 100 |
src/lib | 100 | 100 | 100 | 100 |
xpm-liquid.ts | 100 | 100 | 100 | 100 |
----------------|---------|----------|---------|---------|-------------------To run a specific test with more verbose output, use npm run tap:
% npm run tap tests/tap/010-functions.ts
> @xpack/[email protected] tap /Users/ilg/My Files/WKS Projects/xpack.github/npm-packages/xpm-liquid-ts.git
> tap --reporter=spec "tests/tap/010-functions.ts"
(node:32977) ExperimentalWarning: --experimental-loader is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
tests/tap/010-functions.ts
filterPath
✓ preserves posix path separator /
✓ preserves windows path separator \
✓ preserves posix path separator /
✓ replaces by dash
✓ replaces by dash
✓ replaces by dash
✓ replaces two dashes
✓ replaces three dashes
8 passing (1s)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).
Thus, passing coverage tests was enforced for all tests, as seen before.
Exclusions are marked with /* istanbul ignore next */ for
istanbul
and /* c8 ignore start */ /* c8 ignore stop */ for
c8.
- an extra test to catch ineffective substitutions
- a platform dependent logic in the
filterPath()function
The continuous integration tests are performed via GitHub Actions on Ubuntu, Windows and macOS, using node 16, 18.
To trace module resolution:
"compile": "tsc --traceResolution -p ./",There are no fixed releases.
In the xpack/xpm-liquid-ts Git repo:
- switch to the
developbranch - if needed, merge the
masterbranch
No need to add a tag here, it'll be added when the release is created.
Notice: this package is also used by the VS Code extension and must be kept as a legacy CommonJS dependency.
npm outdatednpm updateor edit andnpm install- repeat and possibly manually edit
package.jsonuntil everything is up to date - commit the changes
Keep:
@types/nodelocked to the oldest supported node (^18.11.9) release available for TypeScript.- tap 16.3.4
To be updated when fully migrated to ESM.
As required by npm modules, this one also uses semver.
Determine the next version (like 2.0.0),
and eventually update the
package.json file; the format is 2.0.0-pre.
Check GitHub issues and pull requests:
Update the README-MAINTAINER.md file to reflect the changes
related to the new version.
- check the latest commits
npm run git-log - open the
CHANGELOG.mdfile - check if all previous fixed issues are in
- add a line * v2.0.0 released
- commit with a message like prepare v2.0.0
- terminate all running tasks (Terminal → Terminate Task...)
- select the
developbranch - commit everything
npm run fix- in the develop branch, commit all changes
npm run testnpm run typedocand open thedocs/index.htmlin a browsernpm run pack; check the list of packaged files, possibly update.npmignorenpm version patch(bug fixes),npm version minor(compatible API additions),npm version major(incompatible API changes)- push all changes to GitHub;
- the
postversionnpm script should also update tags viagit push origin --tags; this should trigger CI - wait for CI tests to complete
- check https://github.com/xpack/xpm-liquid-ts/actions/
npm publish --tag next(use--access publicwhen publishing for the first time)
Check if the version is present at @xpack/xpm-liquid Versions.
Test it with:
npm install -global @xpack/xpm-liquid@nextIn this Git repo:
- select the
masterbranch - merge
develop - push all branches
In https://github.com/xpack/xpm-liquid-ts/milestones:
- close the current milestone.
The documentation site is built with TypeDoc and published in the project GitHub Pages.
The Web site deployment is performed automatically when pushing to the master branch, by a dedicated workflow in GitHub Actions.
When the release is considered stable, promote it as latest:
npm dist-tag ls @xpack/xpm-liquidnpm dist-tag add @xpack/[email protected] latestnpm dist-tag ls @xpack/xpm-liquid