|
| 1 | +# Backward compatibility policy for arduino-cli. |
| 2 | + |
| 3 | +The arduino-cli project follows a strict semantic versioning policy. We are committing not to make breaking changes in |
| 4 | +minor releases after the release of version 1.0.0. The project is currently in the last period of the Beta phase. |
| 5 | + |
| 6 | +The release rules are the following: |
| 7 | + |
| 8 | +- Alpha phase `0.0.X`: In this phase, the software is going through a quick iteration of the API, each release (with |
| 9 | + increments of X) may contain massive and breaking changes. |
| 10 | +- **Beta phase `0.Y.X`**: The software is usable, but the API is still not settled and is under continuous testing and |
| 11 | + review. Breaking changes are expected. Bug fixes and new features are made as patch releases (with increments of X). |
| 12 | + Breaking changes due to API refinements are made as minor releases (with increments of Y). |
| 13 | +- Production release-candidate `1.0.0-rc.X`: in this phase, the software is considered ready for release and distributed |
| 14 | + to the users for final testing. Release candidates (with increments of X) are possible for bug fixes only. |
| 15 | +- Production release `1.Y.X`: For the production releases backward compatibility is guaranteed, and all the breaking |
| 16 | + changes are cumulated for the next major release (2.0.0). Bug fixes are made as patch releases (with increments of X); |
| 17 | + New features are released as minor releases (with increments of Y). |
| 18 | +- Next major release development `2.0.0` and up: see below. |
| 19 | + |
| 20 | +## Backward compatibility guarantees and definition of "breaking change" |
| 21 | + |
| 22 | +There are three main user facing API in the arduino-cli project: |
| 23 | + |
| 24 | +- the standalone command-line API |
| 25 | +- the gRPC API |
| 26 | +- the golang API |
| 27 | + |
| 28 | +Let's examine the backward compatibility rules for each one of these categories. |
| 29 | + |
| 30 | +### Breaking changes in the command-line app |
| 31 | + |
| 32 | +Changes in the command-line interface are considered breaking if: |
| 33 | + |
| 34 | +- a command, a positional argument, or a flag is removed or renamed |
| 35 | +- a command, a positional argument, or a flag behavior is changed |
| 36 | +- an optional positional argument or a flag is made mandatory |
| 37 | +- a positional argument or a flag format is changed |
| 38 | + |
| 39 | +The following changes to the command-line syntax are NOT considered breaking: |
| 40 | + |
| 41 | +- a new command is added |
| 42 | +- a new optional positional argument is added |
| 43 | +- a new optional flag is added |
| 44 | + |
| 45 | +Any change in the **human-readable** text output is **NOT** considered a breaking change. In general, the human-readable |
| 46 | +text is subject to translation and small adjustments in natural language syntax and presentation. |
| 47 | + |
| 48 | +We will consider breaking changes only in the **machine-readable** output of the commands using the `--format json` |
| 49 | +flag. In particular, we have a breaking change in the JSON command output if: |
| 50 | + |
| 51 | +- a key in a JSON object is renamed or removed. |
| 52 | +- a value in a JSON object or array changes meaning or changes format. |
| 53 | + |
| 54 | +We do **NOT** have a breaking change if: |
| 55 | + |
| 56 | +- a new key is added to an existing JSON object |
| 57 | + |
| 58 | +### Breaking changes in the gRPC API |
| 59 | + |
| 60 | +To ensure gRPC API backward compatibility the only allowed changes are: |
| 61 | + |
| 62 | +- adding a new service |
| 63 | +- adding a new method to a service |
| 64 | +- adding a field to an existing message |
| 65 | +- adding a value to an enum |
| 66 | + |
| 67 | +In general, **adding** to the gRPC API is allowed, **ANY OTHER** change will be considered a breaking change, some |
| 68 | +examples are: |
| 69 | + |
| 70 | +- renaming a service |
| 71 | +- renaming a method |
| 72 | +- changing a method signature |
| 73 | +- renaming a field in a message |
| 74 | +- changing a field type in a message |
| 75 | +- deleting a field in a message |
| 76 | +- etc. |
| 77 | + |
| 78 | +The gRPC API is defined as a gRPC service running in the endpoint `cc.arduino.cli.commands.v1`. When a breaking change |
| 79 | +happens a new gRPC endpoint is created from the existing API. The first breaking change will be implemented in the new |
| 80 | +service `cc.arduino.cli.commands.v2`. |
| 81 | + |
| 82 | +### Breaking changes in the golang API |
| 83 | + |
| 84 | +The public golang API from the import path `github.com/arduino/arduino-cli` is guaranteed to be stable. Breaking changes |
| 85 | +in the API will follow the go-lang guidelines and will be implemented by changing the import path by adding the `/v2` |
| 86 | +suffix: `github.com/arduino/arduino-cli/v2`. |
| 87 | + |
| 88 | +## Development process for the next major releases. |
| 89 | + |
| 90 | +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 |
| 91 | +that will continue on the `master` git branch. |
| 92 | + |
| 93 | +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 |
| 94 | +2.0 specific change, in that case, it's fine to develop directly on the `2.x.x` branch). |
| 95 | + |
| 96 | +Future releases and pre-releases of the `2.x.x` will follow the following versioning policy: |
| 97 | + |
| 98 | +- Beta `2.0.0-beta.X.Y`: The v2 API is still under testing and review. Bug fixes and new features are released with |
| 99 | + increments of Y. Breaking changes are still possible and released with increments of X. |
| 100 | +- Release Candidate `2.0.0-rc.X`: The v2 API is ready for release. Release candidates are distributed for user testing. |
| 101 | + Bug-fix releases only are allowed (with increments of X). |
| 102 | +- `2.0.0` and up: The same rules for the `1.0.0` applies. |
| 103 | + |
| 104 | +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 |
| 105 | +`1.x.x` branch. |
| 106 | + |
| 107 | +The command-line interface for CLI 2.0 will be incompatible with CLI 1.0. Some commands may still be compatible though |
| 108 | +depending on the amount of changes. |
| 109 | + |
| 110 | +The gRPC daemon is flexible enough to run both services v1 and v2 at the same time. This capability allows a deprecation |
| 111 | +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 |
| 112 | +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 |
| 113 | +API entirely but, depending on the balance between user demand and maintenance effort, we may decide to continue to |
| 114 | +support it. |
| 115 | + |
| 116 | +The go-lang API import path will be updated, following the go modules guidelines, by adding the `/v2` suffix: |
| 117 | +`github.com/arduino/arduino-cli/v2`. |
| 118 | + |
| 119 | +Unlike the gRPC counterpart, we will not guarantee a deprecation policy and a soft transition period for the go-lang API |
| 120 | +(but again depending on the balance between user demand and maintenance effort we may decide to deprecate some API). |
0 commit comments