Skip to content

Commit ffef84b

Browse files
alessio-peruginialessio-perugini
committed
update DOCS
1 parent 0337ee0 commit ffef84b

File tree

3 files changed

+175
-9
lines changed

3 files changed

+175
-9
lines changed

‎docs/UPGRADING.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,166 @@ Here you can find a list of migration guides to handle breaking changes between
44

55
## 0.35.0
66

7+
### CLI `core list` and `core search` changed JSON output.
8+
9+
Below is an example of the response containing an object with all possible keys set.
10+
11+
```json
12+
[
13+
{
14+
"id": "arduino:avr",
15+
"maintainer": "Arduino",
16+
"website": "http://www.arduino.cc/",
17+
"email": "[email protected]",
18+
"indexed": true,
19+
"manually_installed": true,
20+
"deprecated": true,
21+
"releases": {
22+
"1.6.2": {
23+
"name": "Arduino AVR Boards",
24+
"version": "1.6.2",
25+
"type": [
26+
"Arduino"
27+
],
28+
"installed": true,
29+
"boards": [
30+
{
31+
"name": "Arduino Robot Motor"
32+
}
33+
],
34+
"help": {
35+
"online": "http://www.arduino.cc/en/Reference/HomePage"
36+
},
37+
"missing_metadata": true,
38+
"deprecated": true
39+
},
40+
"1.8.3": { ... }
41+
},
42+
"installed_version": "1.6.2",
43+
"latest_version": "1.8.3"
44+
}
45+
]
46+
```
47+
48+
### gRPC `cc.arduino.cli.commands.v1.PlatformSearchResponse` message has been changed.
49+
50+
The old behavior was a bit misleading to the client because, to list all the available versions for each platform, we
51+
used to use the `latest` as it was describing the current platform version. We introduced a new message:
52+
`PlatformSummary`, with the intent to make the response more straightforward and less error-prone.
53+
54+
```protobuf
55+
message PlatformSearchResponse {
56+
// Results of the search.
57+
repeated PlatformSummary search_output = 1;
58+
}
59+
60+
// PlatformSummary is a structure containing all the information about
61+
// a platform and all its available releases.
62+
message PlatformSummary {
63+
// Generic information about a platform
64+
PlatformMetadata metadata = 1;
65+
// Maps version to the corresponding PlatformRelease
66+
map<string, PlatformRelease> releases = 2;
67+
// The installed version of the platform, or empty string if none installed
68+
string installed_version = 3;
69+
// The latest available version of the platform, or empty if none available
70+
string latest_version = 4;
71+
}
72+
```
73+
74+
The new response contains an array of `PlatformSummary`. `PlatformSummary` contains all the information about a platform
75+
and all its available releases. Releases contain all the PlatformReleases of a specific platform, and the key is the
76+
semver string of a specific version. We've added the `installed_version` and `latest_version` to make more convenient
77+
the access of such values in the map. A few notes about the behavior of the `releases` map:
78+
79+
- It can be empty if no releases are found
80+
- It can contain a single-release
81+
- It can contain multiple releases
82+
- If in the request we provide the `manually_installed=true`, the key of such release is an empty string.
83+
84+
### Removed gRPC API: `cc.arduino.cli.commands.v1.PlatformList`, `PlatformListRequest`, and `PlatformListResponse`.
85+
86+
The following gRPC API have been removed:
87+
88+
- `cc.arduino.cli.commands.v1.PlatformList`: you can use the already available gRPC method `PlatformSearch` to perform
89+
the same task. Setting the `all_versions=true` and `manually_installed=true` in the `PlatformSearchRequest` returns
90+
all the data needed to produce the same result of the old api.
91+
- `cc.arduino.cli.commands.v1.PlatformListRequest`.
92+
- `cc.arduino.cli.commands.v1.PlatformListResponse`.
93+
94+
### gRPC `cc.arduino.cli.commands.v1.Platform` message has been changed.
95+
96+
The old `Platform` and other information such as name, website, and email... contained details about the currently
97+
installed version and the latest available. We noticed an ambiguous use of the `latest` field, especially when such a
98+
message came in the `PlatformSearchResponse` response. In that use case, the latest field contained the specific version
99+
of a particular platform: this is a hack because the value doesn't always reflect the meaning of that property. Another
100+
inconsistent case occurs when a platform maintainer changes the name of a particular release. We always pick the value
101+
from the latest release, but this might not be what we want to do all the time. We concluded that the design of that
102+
message isn't something to be considered future-proof proof, so we decided to modify it as follows:
103+
104+
```protobuf
105+
// Platform is a structure containing all the information about a single
106+
// platform release.
107+
message Platform {
108+
// Generic information about a platform
109+
PlatformMetadata metadata = 1;
110+
// Information about a specific release of a platform
111+
PlatformRelease release = 2;
112+
}
113+
114+
// PlatformMetadata contains generic information about a platform (not
115+
// correlated to a specific release).
116+
message PlatformMetadata {
117+
// Platform ID (e.g., `arduino:avr`).
118+
string id = 1;
119+
// Maintainer of the platform's package.
120+
string maintainer = 2;
121+
// A URL provided by the author of the platform's package, intended to point
122+
// to their website.
123+
string website = 3;
124+
// Email of the maintainer of the platform's package.
125+
string email = 4;
126+
// If true this Platform has been installed manually in the user' sketchbook
127+
// hardware folder
128+
bool manually_installed = 5;
129+
// True if the latest release of this Platform has been deprecated
130+
bool deprecated = 6;
131+
// If true the platform is indexed
132+
bool indexed = 7;
133+
}
134+
135+
// PlatformRelease contains information about a specific release of a platform.
136+
message PlatformRelease {
137+
// Name used to identify the platform to humans (e.g., "Arduino AVR Boards").
138+
string name = 1;
139+
// Version of the platform release
140+
string version = 5;
141+
// Type of the platform.
142+
repeated string type = 6;
143+
// True if the platform is installed
144+
bool installed = 7;
145+
// List of boards provided by the platform. If the platform is installed,
146+
// this is the boards listed in the platform's boards.txt. If the platform is
147+
// not installed, this is an arbitrary list of board names provided by the
148+
// platform author for display and may not match boards.txt.
149+
repeated Board boards = 8;
150+
// A URL provided by the author of the platform's package, intended to point
151+
// to their online help service.
152+
HelpResources help = 9;
153+
// This field is true when the platform is installed with the Arduino IDE 1.8.
154+
// If the platform is also not indexed it may fail to work correctly in some
155+
// circumstances, and it may need to be re-installed.
156+
bool missing_metadata = 10;
157+
// True this release is deprecated
158+
bool deprecated = 11;
159+
}
160+
```
161+
162+
To address all the inconsistencies/inaccuracies we introduced two messages:
163+
164+
- `PlatformMetadata` contains generic information about a platform (not correlated to a specific release).
165+
- `PlatformRelease` contains information about a specific release of a platform.
166+
7167
### CLI `debug --info` changed JSON output.
8168

9169
The string field `server_configuration.script` is now an array and has been renamed `scripts`, here an example:

‎rpc/cc/arduino/cli/commands/v1/common.pb.go‎

Lines changed: 8 additions & 5 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎rpc/cc/arduino/cli/commands/v1/common.proto‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -74,13 +74,16 @@ message Programmer {
7474
// Platform is a structure containing all the information about a single
7575
// platform release.
7676
message Platform {
77+
// Generic information about a platform
7778
PlatformMetadata metadata = 1;
79+
// Information about a specific release of a platform
7880
PlatformRelease release = 2;
7981
}
8082

8183
// PlatformSummary is a structure containing all the information about
8284
// a platform and all its available releases.
8385
message PlatformSummary {
86+
// Generic information about a platform
8487
PlatformMetadata metadata = 1;
8588
// Maps version to the corresponding PlatformRelease
8689
map<string, PlatformRelease> releases = 2;
@@ -94,14 +97,14 @@ message PlatformSummary {
9497
// correlated to a specific release).
9598
message PlatformMetadata {
9699
// Platform ID (e.g., `arduino:avr`).
97-
string id = 1; // package + architecture
100+
string id = 1;
98101
// Maintainer of the platform's package.
99-
string maintainer = 2; // from parent-package
102+
string maintainer = 2;
100103
// A URL provided by the author of the platform's package, intended to point
101104
// to their website.
102-
string website = 3; // from parent-package
105+
string website = 3;
103106
// Email of the maintainer of the platform's package.
104-
string email = 4; // from parent-package
107+
string email = 4;
105108
// If true this Platform has been installed manually in the user' sketchbook
106109
// hardware folder
107110
bool manually_installed = 5;

0 commit comments

Comments
 (0)