Skip to content

Commit

Permalink
Merge pull request #738 from particle-iot/chore/sc-126682/update-readme
Browse files Browse the repository at this point in the history
update readme with new pkg structure
  • Loading branch information
hugomontero committed May 14, 2024
2 parents 8294921 + 55c6c60 commit ff4ee61
Show file tree
Hide file tree
Showing 3 changed files with 38 additions and 32 deletions.
1 change: 0 additions & 1 deletion .github/workflows/dev.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ on:
push:
branches:
- '**'
- '!master'
- '!staging'
jobs:
call-tests:
Expand Down
44 changes: 27 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[![npm](https://img.shields.io/npm/v/particle-cli.svg?style=flat-square)](https://www.npmjs.com/package/particle-cli) [![Build Status](https://circleci.com/gh/particle-iot/particle-cli/tree/master.svg?style=svg)](https://circleci.com/gh/particle-iot/particle-cli/tree/master) [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg?style=flat-square)](https://github.com/particle-iot/particle-cli/blob/master/LICENSE)
[![npm](https://img.shields.io/npm/v/particle-cli.svg?style=flat-square)](https://www.npmjs.com/package/particle-cli) ![GitHub Actions](https://github.com/particle-iot/particle-cli/actions/workflows/dev.yml/badge.svg?branch=master) [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg?style=flat-square)](https://github.com/particle-iot/particle-cli/blob/master/LICENSE)

Particle's full-stack Internet of Things (IoT) device platform
gives you everything you need to securely and reliably connect
Expand Down Expand Up @@ -36,20 +36,8 @@ The Particle CLI is a powerful tool for interacting with your IoT devices and th

For end-users, the most up-to-date installation instructions can be found here: [macOS / Linux](https://docs.particle.io/tutorials/developer-tools/cli/#using-macos-or-linux) | [Windows](https://docs.particle.io/tutorials/developer-tools/cli/#using-windows)

Note: On some platforms (e.g. `arm`), additional manual steps are required:

> particle-cli uses npm packages [`node-usb`](https://github.com/tessel/node-usb) and [`node-serialport`](https://github.com/serialport/node-serialport).
> On some environments (ie: Raspberry Pi and Apple M1), `node-serialport` [does not provide prebuild environments](https://github.com/serialport/node-serialport/issues/2292),
> so their npm install script relies on creating a prebuild using node-gyp (See
> [node-gyp requirements](https://github.com/nodejs/node-gyp#on-unix)), and libudev (See [node-usb installation](https://github.com/tessel/node-usb#installation).
> And these must be installed in order for their npm install script to succeed. As well, particle-cli uses openssl.
>
> As an example, to install these dependencies on Raspbian/Debian/Ubuntu:
> ```bash
> sudo apt update && sudo apt upgrade
> sudo apt install build-essential libudev-dev python3 openssl
> ```
Note: Some commands may require `openssl` to be installed on your system.
You can install it using your package manager (e.g. `brew install openssl` on macOS).

## Getting Started

Expand Down Expand Up @@ -137,8 +125,30 @@ The Particle CLI has a number of automated test suites and related commands. The

All tests use [mocha](https://mochajs.org), [chai](https://www.chaijs.com), and [sinon](https://sinonjs.org/) with coverage handled by [nyc](https://github.com/istanbuljs/nyc).

We recommend running locally if you can as it greatly shortens your feedback loop. However, CI also runs against every PR and [error reporting is publicly available](https://app.circleci.com/pipelines/github/particle-iot/particle-cli).

We recommend running locally if you can as it greatly shortens your feedback loop.
However, CI also runs against every PR and [error reporting
is publicly available](https://app.circleci.com/pipelines/github/particle-iot/particle-cli).

## CLI Packaging and Distribution
* Cli is packaged using [pkg](https://github.com/vercel/pkg).
The packaging is done using GitHub Actions
and the executables are uploaded to [binaries.particle.io/particle-cli](https://binaries.particle.io/particle-cli/).
* There are two installers that are created for the CLI:
* Windows installer: `particle-cli-setup.exe` (This is an NSIS installer for Windows).
You can see the installer script here [ParticleCLISetup.nsi](installer/windows/ParticleCLISetup.nsi)
* Unix installer: `install-cli` (This is a shell script that installs the CLI on Unix systems).
You can see the installer script here [install-cli.sh](installer/unix/install-cli)
* The installers are created using GitHub Actions and are uploaded to [binaries.particle.io/particle-cli/installer](https://binaries.particle.io/particle-cli/installer).
* The current supported platforms for the CLI are:
* Windows
* x64
* macOS
* x64
* arm64
* Linux
* x64
* arm64
* arm
## Releasing a new version

See [RELEASE.md](RELEASE.md).
25 changes: 11 additions & 14 deletions RELEASE.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,27 +10,24 @@
- e.g. going from 1.28.1 to 1.28.2 use `npm version patch`
- e.g. going from 1.28.2 to 1.29.0 use `npm version minor`

- `git push && git push --tag`
- `git push origin master --follow-tags`

- This will push the commits and tag created in the previous steps.

- CircleCI will publish to npm when the build succeeds.
- GitHub Actions will publish to npm when the build succeeds.

- Create a release on GitHub with the notes from the `CHANGELOG.md`

## Create a pre-release
## Create a test version on staging

- Switch to a feature branch (if on `master` the prerelease will be published to npm)
- Run the following command:

- `npm version x.y.z-beta.n` where x.y.z is a version not released yet
and beta.n is a name for this prerelease.
- `git push origin ${branch}:staging -f`

- `npm pack` to build a tarball of the CLI.

- `git push && git push --tag`

- Create a pre-release on Github and attach the packed tarball.

- Tell beta users to install with
`npm install -g https://github.com/particle-iot/particle-cli/releases/download/vx.y.z-beta.n/particle-cli-x.y.z-beta.n.tgz`
- In case you need to change the version, you can run the following command:

- `npm version <major | minor | patch>`
- Make sure to remove the created tag with `git tag -d vX.Y.Z` to prevent publishing to production.
- Then, push the changes to staging again.
- Once you are happy with the changes, you can proceed to merge the changes to master, remember to remove the version commit you just created.
- The executables will be available on `binaries.staging.particle.io/particle-cli/` for testing.

0 comments on commit ff4ee61

Please sign in to comment.