Skip to content

Latest commit

 

History

History
393 lines (277 loc) · 12.2 KB

README-MAINTAINER.md

File metadata and controls

393 lines (277 loc) · 12.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-modules && cd ${HOME}/Work/npm-modules
git clone \
https://github.com/xpack/logger-ts.git logger-ts.git

For development, to clone the develop branch, use:

git clone --branch develop \
https://github.com/xpack/logger-ts.git logger-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 logger-ts.git
npm link

And in the projects referring it:

npm link @xpack/logger

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 & 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:

Standard style

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-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/[email protected] fix
> ts-standard --fix src && standard --fix test
...

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 logger-ts.git
npm install
npm run test

A 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-modules/logger-ts.git
> npm run lint

> @xpack/[email protected] lint /Users/ilg/My Files/WKS Projects/xpack.github/npm-modules/logger-ts.git
> ts-standard src && standard esm

> @xpack/[email protected] test-100-c8 /Users/ilg/My Files/WKS Projects/xpack.github/npm-modules/logger-ts.git
> npm run test-tap-coverage-100-c8 -s

(node:11770) 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:11771) 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:11773) 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:11774) 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:11775) 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:11772) 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:11776) 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:11777) 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-mock-console.ts ......................... 7/7
tests/tap/020-logger-single.ts ......    [ 'trace: trace\n' ]
tests/tap/020-logger-single.ts .................... 185/185
tests/tap/030-logger-multi.ts ..................... 184/184
tests/tap/040-is-level.ts ........................... 81/81
tests/tap/050-buffer.ts ........................... 108/108
tests/tap/060-logger-empty.ts ....................... 25/25
tests/tap/070-logger-default.ts ....................... 2/2
tests/tap/080-undefined.ts .......................... 38/38
total ............................................. 630/630

  630 passing (5s)

  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 |
  logger.ts |     100 |      100 |     100 |     100 |
------------|---------|----------|---------|---------|-------------------

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

% npm run tap tests/tap/010-mock-console.ts

> @xpack/[email protected] tap /Users/ilg/My Files/WKS Projects/xpack.github/npm-modules/logger-ts.git
> tap --reporter=spec "tests/tap/010-mock-console.ts"

(node:33235) 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-mock-console.ts
  mock console
    ✓ stdout is empty
    ✓ stderr is empty
    ✓ stdout has one entry
    ✓ stdout is output
    ✓ stderr is empty
    ✓ stderr has one entry
    ✓ stderr is error

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

  • none

Continuous Integration (CI)

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

Tricks & tips

To trace module resolution:

    "compile": "tsc --traceResolution  -p ./",

How to make new releases

Release schedule

There are no fixed releases.

Check Git

In the xpack/logger-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

Notice: this package is also used by the VS Code extension and must be kept as a legacy CommonJS dependency.

  • 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 6.0.0), and eventually update the package.json file; the format is 6.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 * v6.0.0 released
  • commit with a message like prepare v6.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/logger-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/logger Versions.

Test

Test it with:

npm install -global @xpack/logger@next

Merge into master

In this Git repo:

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

Close milestone

In https://github.com/xpack/xpm-liquid-ts/milestones:

  • close the current milestone.

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/logger
  • npm dist-tag add @xpack/[email protected] latest
  • npm dist-tag ls @xpack/logger

Useful links