mirror of
https://github.com/balena-io/balena-cli.git
synced 2024-12-21 22:47:48 +00:00
66 lines
3.3 KiB
Markdown
66 lines
3.3 KiB
Markdown
|
# 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/run`. 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](http://semver.org/). 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](https://github.com/balena-io/docs/) GitHub repo for publishing at the [CLI
|
||
|
|
Documentation page](https://www.balena.io/docs/reference/cli/).
|
||
|
|
|
||
|
|
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`](https://github.com/balena-io/balena-cli/blob/master/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](https://www.msys2.org/) 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](https://coffeescript.org), but we decided to
|
||
|
|
migrate to [TypeScript](https://www.typescriptlang.org/) 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](https://github.com/balena-io/capitano) was originally adopted as the CLI's
|
||
|
|
framework, but we recently decided to take advantage of [oclif](https://oclif.io/)'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).
|