development.md

Notes on developing ChowChow itself

❗️TODO needs updating for 0.7.x ?

Table of contents

• Setup
• Regular use
  • Irregular use
• Code formatting
• Testing
• Deployment

ChowChow is written in TypeScript and is published through npm and of course follows semantic versioning.

Setup

To develop on this repo you will need to have node.js and npm installed on your dev machine and have an understanding of them. This guide assumes you have the repo checked out and are on macOS, but equivalent commands are available.

You'll only need to follow this setup once for your dev machine.

# Clone the repo
git clone git@github.com:robb-j/chowchow.git

# Install dependancies
npm install

Regular use

These are the commands you'll regularly run to develop the package, in no particular order. You should follow TDD (Test Driven Development), so every change should have a test.

# Run unit tests
# -> Looks for files named `*.spec.ts` in the src directory
npm run test

# Run unit tests and generate code coverage
# -> Uses the same glob as `npm run test`
npm run coverage

Irregular use

These are commands you might need to run but probably won't, also in no particular order.

# Generate the table of contents for this readme
# -> It'll replace content between the toc-head and toc-tail HTML comments
npm run gen:toc

# Manually lint code with TypeScript's `tsc`
npm run lint

# Manually format code
# -> This repo is setup to automatically format code on git-push
npm run prettier

# Manually trans-pile TypeScript to JavaScript
# -> Writes files to dist
npm run build

Code formatting

This repo uses Prettier to automatically format code to a consistent standard. This works using the husky and lint-staged packages to automatically format code whenever you commit code. This means that code that is pushed to the repo is always formatted to a consistent standard.

You can manually run the formatter with npm run prettier if you want.

Prettier is slightly configured in .prettierrc.yml and also ignores files using .prettierignore.

Testing

This repo uses unit tests to ensure that everything is working correctly, guide development, avoid bad code and reduce defects. The Jest package is used to run unit tests. Tests are any file in src/ that end with .spec.ts, by convention they are inline with the source code, in a parallel folder called __tests__.

# Run the tests
npm test -s

# Generate code coverage
npm run coverage -s

Deployment

To deploy a new version of the package run:

# Create a new version of the package
# -> You should be on the master branch
# -> You should have no un-staged changes
# -> This will run unit tests and trans-pile TypeScript to JavaScript
npm version # patch | minor | major

# Publish your new version
npm publish