balena-cli/CONTRIBUTING.md

Contributing

The balena CLI is an open source project and your contribution is welcome!

After cloning this repository and running npm install, the CLI can be built with npm run build and executed with ./bin/balena. In order to ease development:

• npm run build:fast skips some of the build steps for interactive testing, or
• ./bin/balena-dev uses ts-node/register and coffeescript/register to transpile on the fly.

Before opening a PR, please be sure to test your changes with npm test.

Semantic versioning and commit messages

The CLI version numbering adheres to Semantic Versioning. The following header/row is required in the body of a commit message, and will cause the CI build to fail if absent:

Change-type: patch|minor|major

Version numbers and commit messages are automatically added to the CHANGELOG.md file by the CI build flow, after a pull request is merged. It should not be manually edited.

Editing documentation files (CHANGELOG, README, website...)

The doc/cli.markdown file is automatically generated by running npm run build:doc (which also runs as part of npm run build). That file is then pulled by scripts in the balena-io/docs GitHub repo for publishing at the CLI Documentation page.

The content sources for the auto generation of doc/cli.markdown are:

• Selected sections of the README file.
• The CLI's command documentation in source code (both Capitano and oclif commands), for example:
  • lib/actions/build.coffee
  • lib/actions-oclif/env/add.ts

The README file is manually edited, but subsections are automatically extracted for inclusion in doc/cli.markdown by the getCapitanoDoc() function in automation/capitanodoc/capitanodoc.ts.

The INSTALL.md and TROUBLESHOOTING.md files are also manually edited.

Windows

Please note that npm run build:installer (which generates the .exe executable installer on Windows) requires MSYS2 to be installed. Other than that, the standard Command Prompt or PowerShell can be used.

TypeScript vs CoffeeScript, and Capitano vs oclif

The CLI was originally written in CoffeeScript, but we decided to migrate to TypeScript in order to take advantage of static typing and formal programming interfaces. The migration is taking place gradually, as part of maintenance work or the implementation of new features.

Similarly, Capitano was originally adopted as the CLI's framework, but we recently decided to take advantage of oclif's features such as native installers for Windows, macOS and Linux, and support for custom flag parsing (for example, we're still battling with Capitano's behavior of dropping leading zeros of arguments that look like integers such as some abbreviated UUIDs, and migrating to oclif is a solution). Again the migration is taking place gradually, with some CLI commands parsed by oclif and others by Capitano (a simple command line pre-parsing takes place in app.ts to decide whether to route full parsing to Capitano or oclif).