From 088704a360af0c34f1065fbacf64a056fccadd15 Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Fri, 1 Dec 2023 16:02:25 +0100 Subject: [PATCH 1/2] Added versioning/upgrading policy --- docs/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/index.md b/docs/index.md index 2819e36b837..dcc6b351633 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,6 +17,10 @@ Follow the [Getting started guide] to see how to use the most common CLI command The [client_example] folder contains a sample program that shows how to use the gRPC interface of the CLI. Available services and messages are detailed in the [gRPC reference] pages. +## Versioning and backward compatibility policy + + + [installation]: installation.md [getting started guide]: getting-started.md [client_example]: https://github.com/arduino/arduino-cli/blob/master/rpc/internal/client_example From 0c81f39eeb54d6b6e4cdc76f6a8e16000c3336af Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Mon, 18 Dec 2023 21:02:09 +0100 Subject: [PATCH 2/2] Added backward compatibility policy --- docs/index.md | 4 +- docs/versioning.md | 120 +++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 124 insertions(+), 1 deletion(-) create mode 100644 docs/versioning.md diff --git a/docs/index.md b/docs/index.md index dcc6b351633..b02aa1a4b4c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,9 +19,11 @@ services and messages are detailed in the [gRPC reference] pages. ## Versioning and backward compatibility policy - +This software is currently under active development: anything can change at any time, API and UI must be considered +unstable until we release version 1.0.0. For more information see our [versioning and backward compatibility] policy. [installation]: installation.md [getting started guide]: getting-started.md [client_example]: https://github.com/arduino/arduino-cli/blob/master/rpc/internal/client_example [grpc reference]: rpc/commands.md +[versioning and backward compatibility]: versioning.md diff --git a/docs/versioning.md b/docs/versioning.md new file mode 100644 index 00000000000..ef8977300ba --- /dev/null +++ b/docs/versioning.md @@ -0,0 +1,120 @@ +# Backward compatibility policy for arduino-cli. + +The arduino-cli project follows a strict semantic versioning policy. We are committing not to make breaking changes in +minor releases after the release of version 1.0.0. The project is currently in the last period of the Beta phase. + +The release rules are the following: + +- Alpha phase `0.0.X`: In this phase, the software is going through a quick iteration of the API, each release (with + increments of X) may contain massive and breaking changes. +- **Beta phase `0.Y.X`**: The software is usable, but the API is still not settled and is under continuous testing and + review. Breaking changes are expected. Bug fixes and new features are made as patch releases (with increments of X). + Breaking changes due to API refinements are made as minor releases (with increments of Y). +- Production release-candidate `1.0.0-rc.X`: in this phase, the software is considered ready for release and distributed + to the users for final testing. Release candidates (with increments of X) are possible for bug fixes only. +- Production release `1.Y.X`: For the production releases backward compatibility is guaranteed, and all the breaking + changes are cumulated for the next major release (2.0.0). Bug fixes are made as patch releases (with increments of X); + New features are released as minor releases (with increments of Y). +- Next major release development `2.0.0` and up: see below. + +## Backward compatibility guarantees and definition of "breaking change" + +There are three main user facing API in the arduino-cli project: + +- the standalone command-line API +- the gRPC API +- the golang API + +Let's examine the backward compatibility rules for each one of these categories. + +### Breaking changes in the command-line app + +Changes in the command-line interface are considered breaking if: + +- a command, a positional argument, or a flag is removed or renamed +- a command, a positional argument, or a flag behavior is changed +- an optional positional argument or a flag is made mandatory +- a positional argument or a flag format is changed + +The following changes to the command-line syntax are NOT considered breaking: + +- a new command is added +- a new optional positional argument is added +- a new optional flag is added + +Any change in the **human-readable** text output is **NOT** considered a breaking change. In general, the human-readable +text is subject to translation and small adjustments in natural language syntax and presentation. + +We will consider breaking changes only in the **machine-readable** output of the commands using the `--format json` +flag. In particular, we have a breaking change in the JSON command output if: + +- a key in a JSON object is renamed or removed. +- a value in a JSON object or array changes meaning or changes format. + +We do **NOT** have a breaking change if: + +- a new key is added to an existing JSON object + +### Breaking changes in the gRPC API + +To ensure gRPC API backward compatibility the only allowed changes are: + +- adding a new service +- adding a new method to a service +- adding a field to an existing message +- adding a value to an enum + +In general, **adding** to the gRPC API is allowed, **ANY OTHER** change will be considered a breaking change, some +examples are: + +- renaming a service +- renaming a method +- changing a method signature +- renaming a field in a message +- changing a field type in a message +- deleting a field in a message +- etc. + +The gRPC API is defined as a gRPC service running in the endpoint `cc.arduino.cli.commands.v1`. When a breaking change +happens a new gRPC endpoint is created from the existing API. The first breaking change will be implemented in the new +service `cc.arduino.cli.commands.v2`. + +### Breaking changes in the golang API + +The public golang API from the import path `github.com/arduino/arduino-cli` is guaranteed to be stable. Breaking changes +in the API will follow the go-lang guidelines and will be implemented by changing the import path by adding the `/v2` +suffix: `github.com/arduino/arduino-cli/v2`. + +## Development process for the next major releases. + +The development of the 2.0.0 release will proceed in a separate git branch `2.x.x`, in parallel with the 1.0.0 releases +that will continue on the `master` git branch. + +New features and bug fixes should be made on the `master` branch and ported to the `2.x.x` once completed (unless it's a +2.0 specific change, in that case, it's fine to develop directly on the `2.x.x` branch). + +Future releases and pre-releases of the `2.x.x` will follow the following versioning policy: + +- Beta `2.0.0-beta.X.Y`: The v2 API is still under testing and review. Bug fixes and new features are released with + increments of Y. Breaking changes are still possible and released with increments of X. +- Release Candidate `2.0.0-rc.X`: The v2 API is ready for release. Release candidates are distributed for user testing. + Bug-fix releases only are allowed (with increments of X). +- `2.0.0` and up: The same rules for the `1.0.0` applies. + +After the 2.0.0 release, the `master` branch will be moved to `2.x.x`, and the 1.0 branch will be tracked by a new +`1.x.x` branch. + +The command-line interface for CLI 2.0 will be incompatible with CLI 1.0. Some commands may still be compatible though +depending on the amount of changes. + +The gRPC daemon is flexible enough to run both services v1 and v2 at the same time. This capability allows a deprecation +period to allow a soft transition from v1 API to v2 API. We will deprecate the v1 API in the CLI 2.0 series but we will +continue to support it until the next major release CLI 3.0. At that point, we may decide to drop the support for the v1 +API entirely but, depending on the balance between user demand and maintenance effort, we may decide to continue to +support it. + +The go-lang API import path will be updated, following the go modules guidelines, by adding the `/v2` suffix: +`github.com/arduino/arduino-cli/v2`. + +Unlike the gRPC counterpart, we will not guarantee a deprecation policy and a soft transition period for the go-lang API +(but again depending on the balance between user demand and maintenance effort we may decide to deprecate some API). diff --git a/mkdocs.yml b/mkdocs.yml index 9631f87e1f6..59bd3a0128a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -112,6 +112,7 @@ nav: - Package index specification: package_index_json-specification.md - Guides: - Secure boot: guides/secure-boot.md + - Backward compatibility policy: versioning.md extra: version: