Particle Commands

UX-neutral commands for developer tools

Installation | Development | Conventions | Docs | Releasing | License

Installation

1. Install Node.js [[email protected] and [email protected] are required]
2. Clone this repository $ git clone [email protected]:particle-iot/particle-commands.git && cd ./particle-commands
3. Install dependencies $ npm install
4. View available commands $ npm run
5. Run the tests $ npm test
6. 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

• Mocha
• Chai
• Sinon
• NYC

Releasing

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

1. make sure you have the latest:
   • $ git checkout main
   • $ git pull
2. make sure tests pass
   • $ npm test
3. 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.
4. push your tags:
   • $ git push origin main --follow-tags
5. CircleCI will publish the npm package to the latest tag
6. Create a release on GitHub with the notes from the CHANGELOG.md
7. Point your project to the new version npm install particle-commands@latest

License

Copyright © 2016 Particle Industries, Inc. Released under the Apache 2.0 license. See LICENSE for details.