From 6e7f51758e9fcf0bb7d17d13401ed0fd91db6d51 Mon Sep 17 00:00:00 2001 From: Paulo Castro Date: Sat, 25 May 2019 22:11:26 +0100 Subject: [PATCH] Add CONTRIBUTING.md and some guidance on commit messages and doc files. Change-type: patch Signed-off-by: Paulo Castro --- CONTRIBUTING.md | 65 ++++++++++++++++++++++++++++ README.md | 42 +++++------------- doc/cli.markdown | 21 ++++----- lib/actions-oclif/env/add.ts | 6 +-- lib/actions/environment-variables.ts | 2 +- 5 files changed, 92 insertions(+), 44 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..955726fa --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# 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). diff --git a/README.md b/README.md index 60ac4ee8..0bf1e2c5 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,10 @@ are supported. We are aware of users also having a good experience with alternat including: * Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) - (a.k.a. Microsoft's "bash for Windows 10"). -* [Git for Windows](https://git-for-windows.github.io/). -* [MinGW](http://www.mingw.org): install the `msys-rsync` and `msys-openssh` packages too. + (a.k.a. Microsoft's "bash for Windows 10") +* [Git for Windows](https://git-for-windows.github.io/) +* [MSYS](http://www.mingw.org/wiki/MSYS) and [MSYS2](https://www.msys2.org/) (install the + `msys-rsync` and `msys-openssh` packages too) On **macOS** and **Linux,** the standard terminal window is supported. _Optionally,_ `bash` command auto completion may be enabled by copying the @@ -52,14 +53,14 @@ $ balena login HTTP(S) proxies can be configured through any of the following methods, in order of preference: -* Set the \`BALENARC_PROXY\` environment variable in URL format (with protocol, host, port, and +* Set the `BALENARC_PROXY` environment variable in URL format (with protocol, host, port, and optionally basic auth). * Alternatively, use the [balena config file](https://www.npmjs.com/package/balena-settings-client#documentation) - (project-specific or user-level) and set the \`proxy\` setting. It can be: + (project-specific or user-level) and set the `proxy` setting. It can be: * A string in URL format, or * An object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control). -* Alternatively, set the conventional \`https_proxy\` / \`HTTPS_PROXY\` / \`http_proxy\` / \`HTTP_PROXY\` -environment variable (in the same standard URL format). +* Alternatively, set the conventional `https_proxy` / `HTTPS_PROXY` / `http_proxy` / `HTTP_PROXY` + environment variable (in the same standard URL format). To get a proxy to work with the `balena ssh` command, check the [installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md). @@ -78,30 +79,11 @@ If you come across any problems or would like to get in touch: * For bug reports or feature requests, [have a look at the GitHub issues or create a new one](https://github.com/balena-io/balena-cli/issues/). -## Contributing +## Contributing (including editing documentation files) -The balena CLI is an open source project and your contribution is welcome! - -The CLI was originally written in [CoffeeScript](https://coffeescript.org), but we have 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. - -After cloning this repository and running `npm install` you can build the CLI using `npm run build`. -You can then run the generated build using `./bin/balena`. -In order to ease development: - -* you can build the CLI using the `npm run build:fast` variant which skips some of the build steps or -* you can use `./bin/balena-dev` which live transpiles the sources of the CLI. - -In either case, before opening a PR be sure to also test your changes with `npm test`. - -## Note on editing this README document - -This file is edited/created by hand, but it is then automatically parsed to extract selected -subsections for the [CLI's web documentation page](https://www.balena.io/docs/reference/cli/). -The code that parses this file is in [`automation/capitanodoc/capitanodoc.ts` -](https://github.com/balena-io/balena-cli/blob/master/automation/capitanodoc/capitanodoc.ts). +Please have a look at the [CONTRIBUTING.md](./CONTRIBUTING.md) file for some guidance before +submitting a pull request or updating documentation (because some files are automatically +generated). Thank you for your help and interest! ## License diff --git a/doc/cli.markdown b/doc/cli.markdown index d5ba6d73..cc616a6e 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -21,9 +21,10 @@ are supported. We are aware of users also having a good experience with alternat including: * Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) - (a.k.a. Microsoft's "bash for Windows 10"). -* [Git for Windows](https://git-for-windows.github.io/). -* [MinGW](http://www.mingw.org): install the `msys-rsync` and `msys-openssh` packages too. + (a.k.a. Microsoft's "bash for Windows 10") +* [Git for Windows](https://git-for-windows.github.io/) +* [MSYS](http://www.mingw.org/wiki/MSYS) and [MSYS2](https://www.msys2.org/) (install the + `msys-rsync` and `msys-openssh` packages too) On **macOS** and **Linux,** the standard terminal window is supported. _Optionally,_ `bash` command auto completion may be enabled by copying the @@ -44,14 +45,14 @@ $ balena login HTTP(S) proxies can be configured through any of the following methods, in order of preference: -* Set the \`BALENARC_PROXY\` environment variable in URL format (with protocol, host, port, and +* Set the `BALENARC_PROXY` environment variable in URL format (with protocol, host, port, and optionally basic auth). * Alternatively, use the [balena config file](https://www.npmjs.com/package/balena-settings-client#documentation) - (project-specific or user-level) and set the \`proxy\` setting. It can be: + (project-specific or user-level) and set the `proxy` setting. It can be: * A string in URL format, or * An object in the [global-tunnel-ng options format](https://www.npmjs.com/package/global-tunnel-ng#options) (which allows more control). -* Alternatively, set the conventional \`https_proxy\` / \`HTTPS_PROXY\` / \`http_proxy\` / \`HTTP_PROXY\` -environment variable (in the same standard URL format). +* Alternatively, set the conventional `https_proxy` / `HTTPS_PROXY` / `http_proxy` / `HTTP_PROXY` + environment variable (in the same standard URL format). To get a proxy to work with the `balena ssh` command, check the [installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md). @@ -635,7 +636,7 @@ device ## env add NAME [VALUE] -Add an enviroment or config variable to an application or device, as selected +Add an environment or config variable to an application or device, as selected by the respective command-line options. If VALUE is omitted, the CLI will attempt to use the value of the environment @@ -659,7 +660,7 @@ environment or config variable name #### VALUE -variable value; if omitted, use value from CLI's enviroment +variable value; if omitted, use value from CLI's environment ### Options @@ -678,7 +679,7 @@ suppress warning messages ## env rename <id> <value> Use this command to change the value of an application or device -enviroment variable. +environment variable. The --device option selects a device instead of an application. diff --git a/lib/actions-oclif/env/add.ts b/lib/actions-oclif/env/add.ts index 00e1d96f..0a9a6a1d 100644 --- a/lib/actions-oclif/env/add.ts +++ b/lib/actions-oclif/env/add.ts @@ -34,9 +34,9 @@ interface ArgsDef { export default class EnvAddCmd extends Command { public static description = stripIndent` - Add an enviroment or config variable to an application or device. + Add an environment or config variable to an application or device. - Add an enviroment or config variable to an application or device, as selected + Add an environment or config variable to an application or device, as selected by the respective command-line options. If VALUE is omitted, the CLI will attempt to use the value of the environment @@ -62,7 +62,7 @@ export default class EnvAddCmd extends Command { name: 'value', required: false, description: - "variable value; if omitted, use value from CLI's enviroment", + "variable value; if omitted, use value from CLI's environment", }, ]; diff --git a/lib/actions/environment-variables.ts b/lib/actions/environment-variables.ts index 4bbcb810..5254e2ed 100644 --- a/lib/actions/environment-variables.ts +++ b/lib/actions/environment-variables.ts @@ -171,7 +171,7 @@ export const rename: CommandDefinition< description: 'rename an environment variable', help: stripIndent` Use this command to change the value of an application or device - enviroment variable. + environment variable. The --device option selects a device instead of an application.