meta: Initial metadata support

[trombik]

see #260 for rationales. the PR includes fixes in build example workflow (master drops make build).

initial tests have been added, but not all components have a metadata file yet (the test fail).

[UncleRus]

How about this format for metadata:

components:
  - name: bmp180
    description: |
      Driver for BMP180 digital pressure sensor
    groups:
      - pressure
      - temperature
    code_owners:
      - UncleRus
    depends:
      - i2cdev
      - log
      - esp_idf_lib_helpers
    thread_safe: yes
    targets:
      - esp32
      - esp8266
    licenses:
      - MIT
    copyrights:
      - name: FrankB
        year: 2015
      - name: UncleRus
        year: 2018
    devices:
      - name: BMP180
        manufacturer: Bosch Sensortec

It's less noisy, adds a "devices" section and defines the first group in the list as the main one.

[trombik]

requiring name when referring to a Resource (objects defined in the specification) is verbose, but has two reasons.

first, it ensures forward-compatibility. the simplest form of referring to something is a dict:

foo:
  bar:
  buz:

foo has two attributes, bar and buz. this would break when you want multiple same attributes at the same time. the second form is a list:

foo:
  - bar
  - buz
  - bar

now you can use two bar. but this would break when bar is not unique. for example, bar has two versions, and you need both. A list of dict is the safest option, such as:

foo:
  - name: bar
    version: 1.0
  - name: buz
  - name: bar
    version: 1.2

for this reason, I even thought that description might deserve Description Resource, such as:

description:
  name: language
  i18n:
    en_US: Language
    th_TH: ภาษา
    ja_JP: 言語

but at the same time, I thought readers should be able to read English, and we should not do i18n.

second reason is, it reduces context switch when writing metadata. it is always name: foo when you refers to a Person. in your example, code_owners requires the value of name of a Person, or foo, but copyrights requires name: foo. "which one should I use here?" is the context switch.

what is the purpose of devices? adding more information about devices? such as:

devices:
  - name: foo
    manufacturer: Bar
    product_url: http://bar.example.org
    datasheet_url: http://bar.example.org/doc/foo.html

please describe what you need in Device Resource.

[trombik]

maybe, copyrights should have been:

copyrights:
 - author:
     name: FrankB
   year: 2015

which is semantically correct. but Copyright will never have multiple authors.

update: the above form is now supported.

[trombik]

I don't think the tests cover all cases. will add more after merged.

[nicola-lunghi]

@UncleRus @trombik

Hi, regarding this, have a look here

https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html

I think espressif is developing their own "component library" manager.
It would be useful to implement their metadata instead or merge the two

[trombik]

i know the manager, and that's a part of purpose of metadata support. but we have our own requirements. when we have metadata, it will be a matter of simple conversion.

[trombik]

for the record, here's my thoughts about dependency.

there would be two kinds of dependency; internal and external. internal dependency is a dependency on components in this repository. external is the one on other components or library we don't manage.

external dependency should be limited to one in esp-idf only. if a component requires third party components or libraries, they should be vendered, i.e include the required sources, like some components written by FastLED. no git submodules, nor any other dependency resolver.

[trombik]

submoduling internal components is acceptable if, and only if, the components are managed by the maintainers, or the same entity that manages this repository, such as a GitHub organization.