Skip to content

README-MAINTAINER.md

Latest commit

 

History

History
374 lines (262 loc) · 11.2 KB

README-MAINTAINER.md

File metadata and controls

374 lines (262 loc) · 11.2 KB

GitHub package.json version npm (scoped) license TS-Standard - TypeScript Standard Style Guide CI on Push GitHub issues GitHub pulls

Maintainer & developer info

Project repository

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/update-checker-ts.git update-checker-ts.git

For development, to clone the develop branch, use:

git clone --branch develop \
https://github.com/xpack/update-checker-ts.git update-checker-ts.git

Prerequisites

The prerequisites are:

  • node >= 16.0.0
  • npm

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

nvm use --lts 16
code

Satisfy dependencies

npm install

Add links for development

cd update-checker-ts.git
npm link

And in the projects referring it:

npm link @xpack/update-checker

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 current version is TypeScript 4:

The compiler is configured to produce es2020 & node16 files, which means ECMAScript6 with Node.js modules, that can be imported by any other ES6 project via import.

For more details on how to configure tsconfig.json, please see:

Standard style

As style, the project uses ts-standard, the TypeScript variant of Standard Style, automatically checked at each commit via CI.

If necessary the syntax for exceptions is:

// eslint-disable-next-line @typescript-eslint/no-xxx-yyy

The 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/update-checker@2.0.0 fix
> ts-standard --fix src tests
...

Documentation metadata

The documentation metadata uses the TypeDoc tags, without explicit types, since they are provided by TypeScript.

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 (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 update-checker-ts.git
npm install
npm run test

A full test run, including coverage, looks like:

% npm run test-100-c8

> @xpack/update-checker@2.0.0 pretest-100-c8 /Users/ilg/My Files/WKS Projects/xpack.github/npm-packages/update-checker-ts.git
> npm run lint

> @xpack/update-checker@2.0.0 lint /Users/ilg/My Files/WKS Projects/xpack.github/npm-packages/update-checker-ts.git
> ts-standard src

> @xpack/update-checker@2.0.0 test-100-c8 /Users/ilg/My Files/WKS Projects/xpack.github/npm-packages/update-checker-ts.git
> npm run test-tap-coverage-100-c8 -s

(node:9919) 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:9920) 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-constructor.ts ........................ 15/15
tests/tap/020-checker.ts ............................ 43/43
total ............................................... 58/58

  58 passing (6s)

  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 |
  update-checker.ts |     100 |      100 |     100 |     100 |
--------------------|---------|----------|---------|---------|-------------------

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

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

> @xpack/update-checker@2.0.0 tap /Users/ilg/My Files/WKS Projects/xpack.github/npm-packages/update-checker-ts.git
> tap --reporter=spec "tests/tap/010-constructor.ts"

(node:10352) 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-constructor.ts
  asserts
    ✓ UpdateChecker is defined
    ✓ MockConsole is defined
    ✓ MockLogger is defined

  constructor with values
    ✓ created
    ✓ logged
    ✓ name ok
    ✓ version ok
    ✓ folder path ok
    ✓ file path ok
    ✓ file suffix ok
    ✓ interval ok

  constructor without values
    ✓ assert(params) throws
    ✓ assert(params.log) throws
    ✓ assert(params.packageName) throws
    ✓ assert(params.packageVersion) throws

  15 passing (1s)

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).

Thus, passing coverage tests was enforced for all tests, as seen before.

Coverage exceptions

Exclusions are marked with /* istanbul ignore next */ for istanbul and /* c8 ignore start */ /* c8 ignore stop */ for c8.

  • in the constructor
    • the tests if running on Windows are skipped, to allow tests to run on Linux/macOS
    • the possible exception when creating the timestamp is not checked

Continuous Integration (CI)

The continuous integration tests are performed via GitHub Actions on Ubuntu, Windows and macOS, using node 16, 18.

How to make new releases

Release schedule

There are no fixed releases.

Check Git

In the xpack/update-checker-ts Git repo:

  • switch to the develop branch
  • if needed, merge the master branch

No need to add a tag here, it'll be added when the release is created.

Update npm packages

  • npm outdated
  • npm update or edit and npm install
  • repeat and possibly manually edit package.json until everything is up to date
  • commit the changes

Keep:

  • @types/node locked to the oldest supported node (^16.18.14) release available for TypeScript.

Determine the next version

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.

Fix possible open issues

Check GitHub issues and pull requests:

Update README-MAINTAINER.md

Update the README-MAINTAINER.md file to reflect the changes related to the new version.

Update CHANGELOG.md

  • check the latest commits npm run git-log
  • open the CHANGELOG.md file
  • check if all previous fixed issues are in
  • add a line * v2.0.0 released
  • commit with a message like prepare v2.0.0

Prepare to publish

  • terminate all running tasks (Terminal → Terminate Task...)
  • select the develop branch
  • commit everything
  • npm run fix
  • in the develop branch, commit all changes
  • npm run test
  • npm run typedoc and open the docs/index.html in a browser
  • npm run pack; check the list of packaged files, possibly update .npmignore
  • npm version patch (bug fixes), npm version minor (compatible API additions), npm version major (incompatible API changes)
  • push all changes to GitHub;
  • the postversion npm script should also update tags via git push origin --tags; this should trigger CI
  • wait for CI tests to complete
  • check https://github.com/xpack/update-checker-ts/actions/

Publish to npmjs.com

  • npm publish --tag next (use --access public when publishing for the first time)

Check if the version is present at @xpack/update-checker Versions.

Test

Test it with:

npm install -global @xpack/update-checker@next

Merge into master

In this Git repo:

  • select the master branch
  • merge develop
  • push all branches

Web site deployment

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.

Tag the npm package as latest

When the release is considered stable, promote it as latest:

  • npm dist-tag ls @xpack/update-checker
  • npm dist-tag add @xpack/update-checker@2.0.0 latest
  • npm dist-tag ls @xpack/update-checker

Useful links