npx-boilerplate

Boilerplate for project repositories that build, maintain and publish @rocketmakers npx and/or npm packages.

Contents

• Steps after cloning - things to do next
• Development - notes on how to do development
• Release process - notes on the release process

Steps after cloning

After cloning this repo, you almost have a fully functional npm package. You will need to do the following things, probably in this order:

Setup up a new git repo

Run the following commands to set up your new repo:

rm -rf .git
git init
# Install in order to enable commitizen
npm run prepare
git branch -m develop
make

Rename the project

Search and replace in the project for npx-boilerplate and replace it with your project name. This should affect:

• package.json, where you will need to update the project name, description, repository url and probably bin entry
• .gitlab-ci.yaml, where you will need to update the notify:release rule's script entry
• package-lock.json, run npm i after editing package.json and this will get updated

Make sure to commit these changes, probably with:

git add --all && git commit -m "Initial commit of boilerplate code"

Create new GitLab repository

Create an empty project in the appropriate Rocketmakers GitLab group. Uncheck the setting 'Initialize repository with a README', so that the repo is empty. There will be a range of command line scripts to set up the repo. From the 'Push an existing folder' line, grab the line that looks like this:

git remote add origin [email protected]:rocketmakers/project-name.git

And run it, and then run:

git push --set-upstream origin develop

In order for the established release pipelines and documentation generation/hosting to work you need to configure the following in your remote repository:

• Either:
  • Ensure your project is under the root Rocketmakers project group in GitLab (should be able to see NPM_TOKEN in your inherited CI/CD variables)
  • Create an npm token for your project and store as the value for NPM_TOKEN CI/CD variable

Set up merge request reminders

In your GitLab project, go to CI/CD -> Schedules, and click New Schedule. You probably want to add a description and pick Interval Pattern: Custom with 54 8 * * 1-5 (this is cron syntax, which is mm hh dd MM day for historical reasons - this suggestion means at 8:54am every Monday-Friday) and Cron Timezone: London.

Find the GitLab Project ID from the home page of your repo, underneath the project name, and then set the following variables:

MERGE_REQUEST_REMINDERS: true
GITLAB_PROJECT_IDS: ${your GitLab Project ID}

By default, this will prompt the #code-reviews channel in Slack, but there are webhook urls for other channels in the Rocketmakers group on GitLab, under Settings -> CI/CD -> Variables, as SLACK_WEBHOOK_URL_{CHANNEL}. If the channel that you want isn't there, there is documentation available on Notion. Once you have a channel variable, update the notify:merge-request-reminder job in .gitlab-ci.yaml, replacing $SLACK_WEBHOOK_URL_CODE_REVIEWS with your chosen variable name.

Re-write this section of the documentation to explain your package

This section of the readme, from 'Steps after cloning' to here should be updated to explain your project.

Development

The boilerplate assumes you use the following git flow:

• feature branches - Local development branches
• develop - Main development branch on origin
• release - Published branch

Before pushing any branch, the project is built using make, tested with jest and linted with eslint on your local environment. If any of these fail, the push will be blocked until they're fixed. Your push will also be blocked if the commited built files don't match the artefact build from commited source code.

Test pipelines are run on every pushed branch, which test the same as the pre-push check, across supported node versions (currently 12, 14, 16 & 18).

Merge requests should be made to develop.

Testing npx scripts

You should write unit tests in the _tests folder to test the functional behaviour of your scripts. As noted above, these will be run frequently to ensure that breaking changes don't slip in.

As well as unit tests, it is possible to test npx scripts in anger, by locally globally installing them:

> npm i -g
> npx npx-boilerplate
Hello, world!
> npm un -g

If you are building an npm package to be imported, you can test it in anger by importing to another project by file, for example:

npm i @rocketmakers/npx-boilerplate@file:../npx-boilerplate

Release process

There are pipelines set up in the boilerplate to target the branch release. When you are happy with your project and want to push it to npm, there's a few steps to complete.

Initial npm publish

You have to do a manual initial publish to npm to set up the project on their end.

First, find someone to add you to the rocketmakers organisation on npm - ask in the #developers channel if you aren't already. Next, make sure you are logged into npm on the command line. To check if you're logged in already, run npm whoami, if not run npm login and follow the steps. You will be emailed a OTP to login.

Then, on the command line run

npm publish --access public

This will push your local branch(!) but connect it to the repo. We have to mark this initial push as public, because scoped packages are private and paid for by default.

Versioning

With appropriate setup, this project uses commitizen to enforce conventional commits. Thanks to this, there is automated version bumping available. Run npm version to update the version number in appropriate places. This will also generate a change log in CHANGELOG.md, according to the commit messages. Run this before merging to release, as the release pipeline will fail if it attempts to release a version number that already exists.

Further releases

After the project exists on npm, merges to the release will automatically run a pipeline that tags git, pushes to npm and publishes documentation to docs.rocketmakers.club. When you want to release, make a merge request from develop to release, and once it is merged, sit back and wait for the pipelines!