Particle-commands NPM

Particle Commands

UX-neutral commands for developer tools

Installation

Install Node.js node@16.x and npm@8.x are required
Clone this repository $ git clone git@github.com:particle-iot/particle-commands.git && cd ./particle-commands
Install dependencies $ npm install
View available commands $ npm run
Run the tests $ npm test
Start Hacking!

Development

All essential commands are available at the root via npm run <script name> - e.g. npm run lint. To view the available commands, run: npm run

to run the tests:

npm test

to run the coverage:

npm run coverage

npm scripts are the primary means of executing programmatic tasks (e.g. tests, linting, releasing, etc) within the repo. to view available scripts, run npm run.

when creating a new script, be sure it does not already exist and use the following naming convention:

<category>:[<subcategory>]:[<action>]

our standard categories include: test, lint, build, clean, docs, package, dependencies, and release. top-level scripts - e.g. npm run clean - will typically run all of its subcategories (e.g. npm run clean:dist && npm run clean:tmp).

npm itself includes special handling for test and start (doc: 1, 2) amongst other lifecycle scripts - use these to expose key testing and start-up commands.

sometimes your new script will be very similar to an existing script. in those cases, try to extend the existing script before adding another one.

Conventions

npm scripts form the developer's API for the repo and all of its packages - key orchestration commands should be exposed here
document developer-facing process / tooling instructions in the Development section
plan to release your changes upon merging to main - refrain from merging if you cannot so you don't leave unpublished changes to others
avoid making changes in files unrelated to the work you are doing so you aren't having to publish trivial updates
test files live alongside their source files and are named like *.test.js or *.spec.js
if the linter does not flag your code (error or warning), it's formatted properly
avoid reformatting unflagged code as it can obscure more meaningful changes and increase the chance of merge conflicts
todo comments include your last name and are formatted like: TODO (mirande): <message>

Docs & Resources

Releasing

Packages are only released from the main branch after peer review.

make sure you have the latest:
- $ git checkout main
- $ git pull
make sure tests pass
- $ npm test
run the version command
- $ npm version <major|minor|patch>
- This command will bump the current version of the library in the package.json file. Before the command finishes, update CHANGELOG.md.
push your tags:
- $ git push origin main --follow-tags
CircleCI will publish the npm package to the latest tag
Create a release on GitHub with the notes from the CHANGELOG.md
Point your project to the new version npm install particle-commands@latest