mirror of
https://github.com/balena-io/balena-cli.git
synced 2025-01-18 02:39:49 +00:00
Add CONTRIBUTING.md and some guidance on commit messages and doc files.
Change-type: patch Signed-off-by: Paulo Castro <paulo@balena.io>
This commit is contained in:
Paulo Castro
parent
ea89a6f221
commit
6e7f51758e
65
CONTRIBUTING.md
Normal file
65
CONTRIBUTING.md
Normal file
@ -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).
|
||||
42
README.md
42
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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
6
lib/actions-oclif/env/add.ts
vendored
6
lib/actions-oclif/env/add.ts
vendored
@ -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",
|
||||
},
|
||||
];
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user