Overview

This repo is for packaging core-js our JS library for importing in to tools across repos.

Code documentation can be found at https://core-js-docs.comcar.co.uk/

3rd party modules

core-js uses the following for releasing and generating documentation:

• Commitzen - to keep commit messages consistent whilst also controlling the release process by incrementing the version number of the package depending on the type of commit message used Commitizen Info
• Semantic-release - to automate the whole package release workflow including: determining the next version number, generating the release notes, and publishing the package. Semantic Release Info
• JSDoc for automated documentation JSDoc Info

Versioning

Follows the SemVer specification for changes:

So for a release with a version number of 8.1.14

• 8 is breaking updates
• 1 is feature updates
• 14 is bug fix updates

Semantic release will update the version number itself by analyzing the commits made.

Committing format

Commitizen will enforce the following commit formats for consistency and to control how semantic-release handles packaging/releases.

Flow

Flow chart source

Release

Packaging

Once merged in to main-v1 dist files are generated by github actions and semantic release so they aren't committed to the repo

Doc generation

When core-js is merged in to main /var/www/vhost/core-js-docs/.git/hooks/post-merge reacts to the merge and does npm run documentation which builds the documentation in to the docs folder

Setup & Development

Force commits to use commitizen

Create the file .git/hooks/prepare-commit-msg with the following as its contents:

#!/bin/bash
exec < /dev/tty && node_modules/.bin/cz --hook || true

Note: You might need to make the hook executable:

chmod +x prepare-commit-msg

Code

Ensure you are writing function comments correctly to ensure consistency and generated documentation works. Here is a vscode snippet:

"function comments": {
		"prefix": "_fn",
		"body": [
		  "/**",
		  " * Description",
		  " * @param {data_type} param_name Description",
		  " * @returns {data_type} Description",
		  " */"
		],
		"description": "function comments"
	  },

Unit tests

• npm run test to run all tests and suites

• npm run test -t <test file> to run single file but seems to work without the -t e.g npm run test tool/forecast/injector.test.js

• npm run test-coverage run tests and output the coverage of unit tests

• To omit a function from test coverage percentage use /* istanbul ignore next */

Release

When you create a PR github actions will run.

Various automated tasks such as linting, coding pattern checks, unit tests etc need to pass in order to allow for the PR to be merged in to main-v1 and a subsequent new release made.

Importing core-js to use

Previously we would create a .npmrc per tool in its root directory but now we just need to ensure there is a .npmrc in our home directory ~/.

In your tool use npm install @carmendata/core-js@1.0.2 where 1.0.2 is the latest version number

Troubleshooting

Setting up the repo for the first time

NPM_TOKEN and GITHUB_TOKEN have been a painful experience. NPM_TOKEN is required to enable publishing and GITHUB_TOKEN is automatically populated (this was from and old comment on trello, needs to be confirmed 19/06/2023)

NPM

When logging in to npm you may also need to include the registry i.e npm login --registry=https://npm.pkg.github.com followed by using my personal access token as the password

Error codes

404

npm ERR! 404 Not Found - GET https://registry.npmjs.org/sstall - Not found

try: log in to npm as per the "NPM" troubleshooting section

405

405 Method Not Allowed - GET https://npm.pkg.github.com/**carmendata**/@sideway/pinpoint/-/pinpoint-2.0.0.tgz

try: npm is looking at our private repo for installing public npm modules. This may be because a .npmrc file is in the tool directory. Remove it.

Not using latest version number when github actions is making a new release

If the current tag is out of date on your branch.

• You can see the current tag with git describe --tags

• If it doesn't match the latest after a git pull origin main-v1

• Do a git fetch to update to the latest tag

• Then git push origin <yourbranchname>