Add CONTRIBUTING.md and some guidance on commit messages and doc files.

Change-type: patch
Signed-off-by: Paulo Castro <paulo@balena.io>

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).

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").
+  (a.k.a. Microsoft's "bash for Windows 10")
-* [Git for Windows](https://git-for-windows.github.io/).
+* [Git for Windows](https://git-for-windows.github.io/)
-* [MinGW](http://www.mingw.org): install the `msys-rsync` and `msys-openssh` packages too.
+* [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,13 +53,13 @@ $ 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\`
+* 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
@@ -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!
+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
-The CLI was originally written in [CoffeeScript](https://coffeescript.org), but we have decided to
+generated). Thank you for your help and interest!
-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).
 
 ## License
 

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").
+  (a.k.a. Microsoft's "bash for Windows 10")
-* [Git for Windows](https://git-for-windows.github.io/).
+* [Git for Windows](https://git-for-windows.github.io/)
-* [MinGW](http://www.mingw.org): install the `msys-rsync` and `msys-openssh` packages too.
+* [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,13 +45,13 @@ $ 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\`
+* 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
@@ -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.
 

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",
 		},
 	];
 

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.