[DESIGN] Tags introduction (#48)

Add design document about the introduction of tags for things and devices

designs/0002-tags.md

@@ -0,0 +1,94 @@
+# Introduction of tags for device and thing
+
+## Review Period
+
+Best before October, 18 2021.
+
+## What is the problem?
+We need to design the commands to **handle tags** for things and devices. Tags could be attached and detached to/from any thing or device. Also, certain commands could take tags as input in order to perform operations on multiple things/devices.
+
+## Out-of-Scope
+
+## User Experience Walkthrough
+
+Example: arduino devices are put in each room of an hotel to control the room lamps.
+The customer needs to have:
+- specific thing template, having a switch variable for each lamp of the room
+- cloud sketch that reacts to changes on the switch variables and controls the lamps
+- specific dashboard template, with all the needed switch widgets
+
+Steps to setup an arduino device:
+- arduino device is provisioned, information about its future location are passed as tags: 
+  `$ arduino-cloud-cli device create -n LedDevice101 --tags location=Milan,room=101,floor=1`
+- thing is created starting from the thing template and bound to the device: 
+  `$ arduino-cloud-cli thing create -n LedThing101 -t LedThingTemplate.yaml `
+  `$ arduino-cloud-cli thing bind -i <thingID> -d <deviceID>`
+- dashboard is created overriding the thing placeholder with the actual thing id:
+  `$ arduino-cloud-cli dashboard create -n LedDashboard101 -t LedDashboardTemplate.yaml --override LedThing=<thingID>`
+- The sketch is uploaded to the device
+
+This steps should be repeated for every arduino device. So, for example, another device in a different room could be provisioned with:   `$ arduino-cloud-cli device create -n LedDevice102 --tags location=Milan,room=102,floor=1`
+
+When the customer wants to update the firmware of the devices, he can use the ota command specifying the tags of the devices to be updated:
+  `$ arduino-cloud-cli ota upload --file <newFirmware.bin> --device-tags floor=1`
+In this case both the devices LedDevice101 and LedDevice102 will be updated.
+
+## Implementation
+
+### Project Changes
+
+Commands to create a device or a thing will accept an optional `--tags` flag. The tags passed in this way will be added to the resource after its creation:
+
+`$ arduino-cloud-cli device create --name <deviceName> --tags <key0>=<value0>,<key1>=<value1>` and same for thing
+
+Commands that could regard multiple things or devices could be changed in order to accept tags.
+
+These commands can be:
+
+**list commands**:
+
+`thing list --tags <key0>=<value0>,<key1>=<value1>` to list all the things having all the tags passed
+
+`device list --tags <key0>=<value0>,<key1>=<value1>` to list all the devices having all the tags passed
+
+
+**delete commands**:
+
+`thing delete --tags <key0>=<value0>,<key1>=<value1>` to delete all the things having all the tags passed
+
+`device delete --tags <key0>=<value0>,<key1>=<value1>` to delete all the devices having all the tags passed
+
+
+**ota command**:
+
+`ota upload --device-tags <key0>=<value0>,<key1>=<value1> --file <sketch-file.ino.bin>` to perform an upload via ota to all the devices having all the tags passed
+
+
+**flags constraints**:
+In delete and ota commands, the `--id` flag should become **optional** instead of mandatory. 
+Then, if neither `--id` nor `--tags` is passed, the command should return an error telling the user to specify at least one of the two flags.
+On the other hand, if both flags are passed, the command should return an error telling to choose only one of the two flags.
+
+**error handling**:
+When a command performs actions on multiple resources, its execution will stop as soon as an error is encountered. 
+
+### Breaking Change
+
+The changes listed above should not break anything, the commands could be used as before.
+
+### Design
+
+New commands should be introduced in order to add and delete tags to devices and things.
+
+`arduino-cloud-cli thing create-tags --thing <thingID> --tags <key0>=<value0>,<key1>=<value1>` and same for device
+
+`arduino-cloud-cli thing delete-tags --thing <thingID> --tags <key0>,<key1>` and same for device
+
+
+### Documentation Changes
+
+Readme should be updated
+
+## Additional Notes
+
+https://arduino.atlassian.net/jira/software/projects/IOT/boards/277?selectedIssue=IOT-1359