eclipse-paho / eclipse-paho/paho.mqtt.javascript

modern JavaScript workflow

Open
#138 9 comments 5 reactions 2 assignees Claimed by @jpwsutton View on GitHub
enhancement
Dominant language
JavaScript
Stars
1.2k
Forks
466
PR merge metrics
No merged PRs in 30d

Description

I spoke with @icraggs today about this project, and I'd like to help move it forward. We need to get MQTT v5 support going, but before that, I'd prefer to udpate the workflow: I'd like to see this fully integrated with npm and Node.js, using a typical toolchain to bundle for the browser. It's not a great developer experience for someone to have to install a Java toolchain to build a JS project.

Here's what needs to happen:

- `package.json`
- [ ] Add missing development dependencies (`devDependencies`); ensure no production dependencies are contained therein (and vice-versa)
- [ ] Upgrade `dependencies`
- [ ] Replace any dependencies that are not Node.js-compatible
- [ ] Add missing fields: `files`, `author`, `keywords`, `main`, `homepage`, `scripts` (see below),`version` (see below), etc.
- [ ] Modify `description` to reflect that it is, indeed, the actual Paho JS client
- [ ] Leverage the `browser` field to point to bundle
- [ ] Add `repository` field (Is it here or `git.eclipse.org`? Please advise)
- [ ] Add `license` field. I expect that's EPL-1.0 as per the [SPDX list](https://spdx.org/licenses/)
- Linting
- [ ] Lint JS and docstrings using the popular and flexible [ESLint](https://eslint.org). Do not need Closure compiler. Configuration and plugins TBD, but [semistandard](https://npmjs.com/package/semistandard) is a reasonable place to start.
- [ ] (Optional) Lint Markdown using [Remark](https://www.npmjs.com/package/remark) or similar tool
- [ ] Add linting scripts to `scripts` prop of `package.json` (should also be invoked via `test` script)
- Tests & CI
- [ ] Execute tests via `test` prop of `scripts`
- [ ] Update `.travis.yml` to build against supported versions of Node.js (I'm thinking v6.x or newer; v4.x will drop out of LTS soon)
- [ ] Run tests in headless Chrome
- [ ] Choose a target browser (e.g. IE11) in preparation for eventually running tests against it (on SauceLabs, for instance)
- Build & bundling
- [ ] Remove Maven and associated `.xml` files
- [ ] Bundle for web with (probably?) Webpack
- [ ] Prepend copyright banner
- [ ] Minify via Uglify plugin
- [ ] Add bundler to `build` script
- Distribution
- [ ] Add `build` script to `prepublishOnly` script; ensure distfiles are listed in `files`
- [ ] Ensure bundle / dist files stay out of version control
- [ ] Do not publish `.zip` archives within the tarball on npm :smile:
- [ ] Use [SemVer](http://semver.org) if not already
- [ ] Create `.zip` file? Not sure how these are used. `.zip` archives are available on GitHub, and tarballs of published packages on npm. Please advise.
- [ ] Add dist file to `browser` field as mentioned earlier
- Documentation
- [ ] Run JSDoc via e.g., `doc` npm script (we can publish this automatically on GitHub Pages at https://eclipse.github.io/paho.mqtt.javascript unless the API docs need to live where they currently live)
- [ ] Add `doc` script to a complete `build` script
- [ ] (Optional) Add `README.md` to the API docs
- [ ] Update `README.md`; add any material changes to install process
- [ ] Update `CONTRIBUTING.md` likewise (maybe move to `.github/` along with `CODE_OF_CONDUCT.md`); it's already out-of-date
- [ ] Figure out what to do with `about.html`
- [ ] Note browser and Node.js compatibliity

Given I have entirely too much experience doing this stuff, it looks like a lot more work than it is. The two "hard" parts are likely going to be:

- Running tests in headless Chrome, because I haven't set that up before. Hoping to avoid having to pull in [Karma](https://npm.im/karma) to do it
- Adding Node.js support & bundling for browser *could* be painful

IMO it's best to knock this out all at once. I am completely new to this codebase, so there may be something I've missed. None of this *should* materially affect production usage of this package apart from potentially a different way to install it.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.