You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by Aled Sage <al...@gmail.com> on 2016/06/20 12:47:09 UTC
[PROPOSAL] catalog YAML format consistency
Hi all,
The YAML format for adding catalog items accepts several different ways
of defining them. This has led to our examples being inconsistent, our
code more complicated, and potential confusion for users when they see
different things that turn out to mean the same.
I think we should standardise on one approach, and deprecate the other ways.
---
_*Current Code*_
An example .bom file is shown below:
brooklyn.catalog:
items:
- id: entity1
version: "1.0.0"
itemType: entity
item:
type: org.apache.brooklyn.entity.machine.MachineEntity
Variants:
* If defining just a single item in the .bom file, you can optionally
miss out the "items".
* You can miss out the "itemType" - it will guess at it by trying to
treat it as an entity, a template, a location or a policy. The
default is "entity".
* You can include "services:" for entity or template types, or you can
miss it out if there is just one entity in the item.
* Similar to "services:", you can include "brooklyn.policies:" or
"brooklyn.locations:".
If itemType is missing, this helps to infer the type. If it does not
agree with itemType, then we add it as the item type and it will
fail later.
* You can define the item metadata at any level - it could be directly
under "brooklyn.catalog" (in which case it applies to all items), or
under a specific item (in which case it overrides any more general
metadata).
An example of a .bom for a single item is shown below:
brooklyn.catalog:
id: entity2
version: "1.0.0"
itemType: entity
item:
type: org.apache.brooklyn.entity.machine.MachineEntity
---
_*Proposal*_
I suggest we have the following stricter rules. Anything else is
deprecated, logging a warning.
* Always include "itemType".
* For entity, policy and location: do not include "services:",
"brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect
exactly one type in the item.
* For template, always expect "services:" (even if there is just one
thing). This is consistent with the YAML required when deploying an
application.
* Always include "items", even if there is just one item in it.
(reasoning: we do not support "service" versus "services", so why
support "item").
We should change the following (breaking backwards compatibility,
because it's really a bug):
* If the itemType differs from the actual type of the item, then fail.
Aled
p.s. I'm in two minds about "item" versus "items": it is simpler with
the single item, and having "item" underneath "items" means it's not
quite like the "services" analogy.
Re: [PROPOSAL] catalog YAML format consistency
Posted by Alex Heneveld <al...@cloudsoftcorp.com>.
I like this direction but I think we should stage as follows:
NOW - agree short-term preferred syntax for catalog items (but nothing
deprecated, not major change)
SOON - define new improved and more powerful syntax, similar to
preferred -- but allowing arbitrary types, interfaces, mixins
My thinking is we need a bigger overhaul (I've been mulling this over)
so let's not do too much churn until then.
--a
On 20/06/2016 13:47, Aled Sage wrote:
> Hi all,
>
> The YAML format for adding catalog items accepts several different
> ways of defining them. This has led to our examples being
> inconsistent, our code more complicated, and potential confusion for
> users when they see different things that turn out to mean the same.
>
> I think we should standardise on one approach, and deprecate the other
> ways.
>
> ---
>
> _*Current Code*_
>
> An example .bom file is shown below:
>
> brooklyn.catalog:
> items:
> - id: entity1
> version: "1.0.0"
> itemType: entity
> item:
> type: org.apache.brooklyn.entity.machine.MachineEntity
>
> Variants:
>
> * If defining just a single item in the .bom file, you can optionally
> miss out the "items".
> * You can miss out the "itemType" - it will guess at it by trying to
> treat it as an entity, a template, a location or a policy. The
> default is "entity".
> * You can include "services:" for entity or template types, or you can
> miss it out if there is just one entity in the item.
> * Similar to "services:", you can include "brooklyn.policies:" or
> "brooklyn.locations:".
> If itemType is missing, this helps to infer the type. If it does not
> agree with itemType, then we add it as the item type and it will
> fail later.
> * You can define the item metadata at any level - it could be directly
> under "brooklyn.catalog" (in which case it applies to all items), or
> under a specific item (in which case it overrides any more general
> metadata).
>
>
> An example of a .bom for a single item is shown below:
>
> brooklyn.catalog:
> id: entity2
> version: "1.0.0"
> itemType: entity
> item:
> type: org.apache.brooklyn.entity.machine.MachineEntity
>
>
> ---
>
> _*Proposal*_
>
> I suggest we have the following stricter rules. Anything else is
> deprecated, logging a warning.
>
> * Always include "itemType".
> * For entity, policy and location: do not include "services:",
> "brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect
> exactly one type in the item.
> * For template, always expect "services:" (even if there is just one
> thing). This is consistent with the YAML required when deploying an
> application.
> * Always include "items", even if there is just one item in it.
> (reasoning: we do not support "service" versus "services", so why
> support "item").
>
>
> We should change the following (breaking backwards compatibility,
> because it's really a bug):
>
> * If the itemType differs from the actual type of the item, then fail.
>
> Aled
>
> p.s. I'm in two minds about "item" versus "items": it is simpler with
> the single item, and having "item" underneath "items" means it's not
> quite like the "services" analogy.
>
>
>
Re: [PROPOSAL] catalog YAML format consistency
Posted by Aled Sage <al...@gmail.com>.
Thanks all.
I've made some PRs [1,2,3] to improve consistency in some minor ways:
* Update docs
* Always include itemType
* Wrap version number in quotes (because a customer hit 1.10 being
changed to 1.1 by yaml parser, and they'd copy-pasted the structure
of the original catalog item).
* Ordering of the first metadata: id, version, itemType.
* Update very old-style brooklyn.catalog that was used in a lot of tests.
* Consistently use "itemType", rather than "item_type" or "item.type".
(If we actually want to support the latter, we should have unit
tests specifically for it, rather than ad hoc usage).
---
For Andrew's suggestion for normative statements, I think those are too
extreme (particularly saying "MUST").
I view this more like the original Java style guide from Sun - it's a
good idea for people to follow it, but we won't fail if you don't follow it.
(But saying that, I do like the way that modern languages like Go will
force you to do things in "the one true way", and fail otherwise. That's
just not appropriate for us, because we want to preserve backwards
compatibility.)
Andrew's list is a good starting point. I'll look at putting something
into the docs. And I will think more about the list as I do it.
I don't think it's worth updating all our existing blueprints
(particularly because we're not certain that the style guide is right),
but it's certainly reasonable to ensure all examples in the docs are
consistent. And to use a style guide as a guide when writing your new
blueprints.
Aled
[1] https://github.com/apache/brooklyn-docs/pull/82
[2] https://github.com/apache/brooklyn-server/pull/222
[3] https://github.com/apache/brooklyn-dist/pull/39
On 28/06/2016 19:18, Mike Zaccardo wrote:
> +1 for agreeing upon a standard syntax, especially because consulting
> existing blueprints is one of the best references when developing a new one.
>
> Alex's staged plan also makes sense to me.
>
> On Mon, Jun 27, 2016 at 8:28 AM Andrew Kennedy <
> andrew.kennedy@cloudsoftcorp.com> wrote:
>
>> +1
>>
>> I agree that we need to maintain consistency in our YAML and BOM files, but
>> not just at the level of Brooklyn item and entity syntax. There should also
>> be a consistent structural format to the files. For example, when
>> specifying configuration, we allow items both inside the `brooklyn.config`
>> map, and outside it. For short examples, missing out `brooklyn.config` is
>> acceptable, but in general we should use it. There should also be
>> consistency in ordering the parts of an entity or catalog entry definition,
>> as well as the formatting of maps, lists and strings.
>>
>> The following is a suggested style guide, for discussion.
>>
>> - https://gist.github.com/grkvlt/62ee0ddeea2f4503f82ad25c2f9b31fd
>>
>> The normative statements are listed here, and the document linked above
>> contains a conforming YAML fragment showing how they are interpreted.
>>
>> 1. Blueprints MUST place all configuration inside a `brooklyn.config` map,
>> and MUST use the fully qualified configuration key name
>> 2. Lists MUST be indented properly, to allow IDE folding to work properly
>> 3. Keywords MUST be formatted as `lowerCamel` tokens
>> 4. Sensor, configuration key and section names MUST be formatted as
>> `lower-hyphen.dot-separated` tokens
>> 5. The preamble for a catalog entry SHOULD contain the following keys,
>> which MUST appear in this order: version, id, name, description, iconUrl,
>> origin, license, licenseUrl, publish
>> 6. Entities SHOULD contain the following sections, which MUST appear in
>> this order: brooklyn.parameters, brooklyn.config, brooklyn.initializers,
>> brooklyn.enrichers, brooklyn.policies, brooklyn.children
>> 7. Catalog items SHOULD contain the following keys, which MUST appear in
>> this order: id, name, description, itemType, item
>> 8. Entities and entity specifications SHOULD contain the following keys,
>> which MUST appear in this order: type, id, name, description, services
>> 9. Names MUST be quoted strings
>> 10. The description value MUST use the multi-line string syntax
>> 11. Parameters SHOULD use the following keys, which MUST appear in this
>> order: name, label, description, type, default, constraints
>>
>> Andrew.
>>
>>
>> On Mon, 20 Jun 2016 at 18:08 Aled Sage <al...@gmail.com> wrote:
>>
>>> Thanks all,
>>>
>>> Alex's suggestion makes a lot of sense. So we should:
>>>
>>> 1. agree short-term preferred syntax
>>> 2. update our docs and examples to *always* use that
>>> 3. discuss improvements for a more powerful syntax, and the longer term
>>> bigger long-term overhaul.
>>>
>>> It should be trivial to warn someone if they have not included the
>>> "itemType", so I think we should do that short-term.
>>>
>>> ---
>>> Any more opinions for the preferred syntax?
>>>
>>> Aled
>>>
>>>
>>> On 20/06/2016 14:44, Geoff Macartney wrote:
>>>> +1 for the proposal, and for staging it.
>>>>
>>>> I actually quite like the suggestion of making items/item entirely
>>> consistent (by requiring both). If I have
>>>> 1 brooklyn.catalog:
>>>> 2 version: "2.0.0-SNAPSHOT"
>>>> 3
>>>> 4 item:
>>>> 5 type: server
>>>> 6 id: testy
>>>> 7 name: Testy McServer
>>>>
>>>> and decide for some reason that I need a second item (maybe move one
>>> here from another file), I can\u2019t just add it below line 7. Instead I
>> have
>>> to go editing lines 3-7 to add \u201citems:\u201d and change the indentation.
>>> Sticking to items+item consistently will make this sort of refactoring
>> less
>>> tedious. Just a thought.
>>>> Geoff
>>>>
>>>>
>>>>
>>>>
>>>> \u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014
>>>> Gnu PGP key - http://is.gd/TTTTuI
>>>>
>>>>
>>>>> On 20 Jun 2016, at 14:17, Svetoslav Neykov <
>>> svetoslav.neykov@cloudsoftcorp.com> wrote:
>>>>> +1 for the proposal.
>>>>>
>>>>> I find the current item-items functionality logical. "item" is used in
>>> leaf items, "items" is used in non-leaf items. Forcing a non-leaf root
>> just
>>> so we always have "items" is overhead.
>>>>> Svet.
>>>>>
>>>>>
>>>>>> On 20.06.2016 \u0433., at 15:47, Aled Sage <al...@gmail.com> wrote:
>>>>>>
>>>>>> Hi all,
>>>>>>
>>>>>> The YAML format for adding catalog items accepts several different
>>> ways of defining them. This has led to our examples being inconsistent,
>> our
>>> code more complicated, and potential confusion for users when they see
>>> different things that turn out to mean the same.
>>>>>> I think we should standardise on one approach, and deprecate the
>> other
>>> ways.
>>>>>> ---
>>>>>>
>>>>>> _*Current Code*_
>>>>>>
>>>>>> An example .bom file is shown below:
>>>>>>
>>>>>> brooklyn.catalog:
>>>>>> items:
>>>>>> - id: entity1
>>>>>> version: "1.0.0"
>>>>>> itemType: entity
>>>>>> item:
>>>>>> type: org.apache.brooklyn.entity.machine.MachineEntity
>>>>>>
>>>>>> Variants:
>>>>>>
>>>>>> * If defining just a single item in the .bom file, you can optionally
>>>>>> miss out the "items".
>>>>>> * You can miss out the "itemType" - it will guess at it by trying to
>>>>>> treat it as an entity, a template, a location or a policy. The
>>>>>> default is "entity".
>>>>>> * You can include "services:" for entity or template types, or you
>> can
>>>>>> miss it out if there is just one entity in the item.
>>>>>> * Similar to "services:", you can include "brooklyn.policies:" or
>>>>>> "brooklyn.locations:".
>>>>>> If itemType is missing, this helps to infer the type. If it does
>> not
>>>>>> agree with itemType, then we add it as the item type and it will
>>>>>> fail later.
>>>>>> * You can define the item metadata at any level - it could be
>> directly
>>>>>> under "brooklyn.catalog" (in which case it applies to all items),
>> or
>>>>>> under a specific item (in which case it overrides any more general
>>>>>> metadata).
>>>>>>
>>>>>>
>>>>>> An example of a .bom for a single item is shown below:
>>>>>>
>>>>>> brooklyn.catalog:
>>>>>> id: entity2
>>>>>> version: "1.0.0"
>>>>>> itemType: entity
>>>>>> item:
>>>>>> type: org.apache.brooklyn.entity.machine.MachineEntity
>>>>>>
>>>>>>
>>>>>> ---
>>>>>>
>>>>>> _*Proposal*_
>>>>>>
>>>>>> I suggest we have the following stricter rules. Anything else is
>>> deprecated, logging a warning.
>>>>>> * Always include "itemType".
>>>>>> * For entity, policy and location: do not include "services:",
>>>>>> "brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect
>>>>>> exactly one type in the item.
>>>>>> * For template, always expect "services:" (even if there is just one
>>>>>> thing). This is consistent with the YAML required when deploying an
>>>>>> application.
>>>>>> * Always include "items", even if there is just one item in it.
>>>>>> (reasoning: we do not support "service" versus "services", so why
>>>>>> support "item").
>>>>>>
>>>>>>
>>>>>> We should change the following (breaking backwards compatibility,
>>> because it's really a bug):
>>>>>> * If the itemType differs from the actual type of the item, then
>> fail.
>>>>>> Aled
>>>>>>
>>>>>> p.s. I'm in two minds about "item" versus "items": it is simpler with
>>> the single item, and having "item" underneath "items" means it's not
>> quite
>>> like the "services" analogy.
>>>>>>
>>> --
>> Andrew Kennedy ; Founder clocker.io project ; @grkvlt ; Cloudsoft
>>
Re: [PROPOSAL] catalog YAML format consistency
Posted by Mike Zaccardo <mi...@cloudsoftcorp.com>.
+1 for agreeing upon a standard syntax, especially because consulting
existing blueprints is one of the best references when developing a new one.
Alex's staged plan also makes sense to me.
On Mon, Jun 27, 2016 at 8:28 AM Andrew Kennedy <
andrew.kennedy@cloudsoftcorp.com> wrote:
> +1
>
> I agree that we need to maintain consistency in our YAML and BOM files, but
> not just at the level of Brooklyn item and entity syntax. There should also
> be a consistent structural format to the files. For example, when
> specifying configuration, we allow items both inside the `brooklyn.config`
> map, and outside it. For short examples, missing out `brooklyn.config` is
> acceptable, but in general we should use it. There should also be
> consistency in ordering the parts of an entity or catalog entry definition,
> as well as the formatting of maps, lists and strings.
>
> The following is a suggested style guide, for discussion.
>
> - https://gist.github.com/grkvlt/62ee0ddeea2f4503f82ad25c2f9b31fd
>
> The normative statements are listed here, and the document linked above
> contains a conforming YAML fragment showing how they are interpreted.
>
> 1. Blueprints MUST place all configuration inside a `brooklyn.config` map,
> and MUST use the fully qualified configuration key name
> 2. Lists MUST be indented properly, to allow IDE folding to work properly
> 3. Keywords MUST be formatted as `lowerCamel` tokens
> 4. Sensor, configuration key and section names MUST be formatted as
> `lower-hyphen.dot-separated` tokens
> 5. The preamble for a catalog entry SHOULD contain the following keys,
> which MUST appear in this order: version, id, name, description, iconUrl,
> origin, license, licenseUrl, publish
> 6. Entities SHOULD contain the following sections, which MUST appear in
> this order: brooklyn.parameters, brooklyn.config, brooklyn.initializers,
> brooklyn.enrichers, brooklyn.policies, brooklyn.children
> 7. Catalog items SHOULD contain the following keys, which MUST appear in
> this order: id, name, description, itemType, item
> 8. Entities and entity specifications SHOULD contain the following keys,
> which MUST appear in this order: type, id, name, description, services
> 9. Names MUST be quoted strings
> 10. The description value MUST use the multi-line string syntax
> 11. Parameters SHOULD use the following keys, which MUST appear in this
> order: name, label, description, type, default, constraints
>
> Andrew.
>
>
> On Mon, 20 Jun 2016 at 18:08 Aled Sage <al...@gmail.com> wrote:
>
> > Thanks all,
> >
> > Alex's suggestion makes a lot of sense. So we should:
> >
> > 1. agree short-term preferred syntax
> > 2. update our docs and examples to *always* use that
> > 3. discuss improvements for a more powerful syntax, and the longer term
> > bigger long-term overhaul.
> >
> > It should be trivial to warn someone if they have not included the
> > "itemType", so I think we should do that short-term.
> >
> > ---
> > Any more opinions for the preferred syntax?
> >
> > Aled
> >
> >
> > On 20/06/2016 14:44, Geoff Macartney wrote:
> > > +1 for the proposal, and for staging it.
> > >
> > > I actually quite like the suggestion of making items/item entirely
> > consistent (by requiring both). If I have
> > >
> > > 1 brooklyn.catalog:
> > > 2 version: "2.0.0-SNAPSHOT"
> > > 3
> > > 4 item:
> > > 5 type: server
> > > 6 id: testy
> > > 7 name: Testy McServer
> > >
> > > and decide for some reason that I need a second item (maybe move one
> > here from another file), I can’t just add it below line 7. Instead I
> have
> > to go editing lines 3-7 to add “items:” and change the indentation.
> > Sticking to items+item consistently will make this sort of refactoring
> less
> > tedious. Just a thought.
> > >
> > > Geoff
> > >
> > >
> > >
> > >
> > > ————————————————————
> > > Gnu PGP key - http://is.gd/TTTTuI
> > >
> > >
> > >> On 20 Jun 2016, at 14:17, Svetoslav Neykov <
> > svetoslav.neykov@cloudsoftcorp.com> wrote:
> > >>
> > >> +1 for the proposal.
> > >>
> > >> I find the current item-items functionality logical. "item" is used in
> > leaf items, "items" is used in non-leaf items. Forcing a non-leaf root
> just
> > so we always have "items" is overhead.
> > >>
> > >> Svet.
> > >>
> > >>
> > >>> On 20.06.2016 г., at 15:47, Aled Sage <al...@gmail.com> wrote:
> > >>>
> > >>> Hi all,
> > >>>
> > >>> The YAML format for adding catalog items accepts several different
> > ways of defining them. This has led to our examples being inconsistent,
> our
> > code more complicated, and potential confusion for users when they see
> > different things that turn out to mean the same.
> > >>>
> > >>> I think we should standardise on one approach, and deprecate the
> other
> > ways.
> > >>>
> > >>> ---
> > >>>
> > >>> _*Current Code*_
> > >>>
> > >>> An example .bom file is shown below:
> > >>>
> > >>> brooklyn.catalog:
> > >>> items:
> > >>> - id: entity1
> > >>> version: "1.0.0"
> > >>> itemType: entity
> > >>> item:
> > >>> type: org.apache.brooklyn.entity.machine.MachineEntity
> > >>>
> > >>> Variants:
> > >>>
> > >>> * If defining just a single item in the .bom file, you can optionally
> > >>> miss out the "items".
> > >>> * You can miss out the "itemType" - it will guess at it by trying to
> > >>> treat it as an entity, a template, a location or a policy. The
> > >>> default is "entity".
> > >>> * You can include "services:" for entity or template types, or you
> can
> > >>> miss it out if there is just one entity in the item.
> > >>> * Similar to "services:", you can include "brooklyn.policies:" or
> > >>> "brooklyn.locations:".
> > >>> If itemType is missing, this helps to infer the type. If it does
> not
> > >>> agree with itemType, then we add it as the item type and it will
> > >>> fail later.
> > >>> * You can define the item metadata at any level - it could be
> directly
> > >>> under "brooklyn.catalog" (in which case it applies to all items),
> or
> > >>> under a specific item (in which case it overrides any more general
> > >>> metadata).
> > >>>
> > >>>
> > >>> An example of a .bom for a single item is shown below:
> > >>>
> > >>> brooklyn.catalog:
> > >>> id: entity2
> > >>> version: "1.0.0"
> > >>> itemType: entity
> > >>> item:
> > >>> type: org.apache.brooklyn.entity.machine.MachineEntity
> > >>>
> > >>>
> > >>> ---
> > >>>
> > >>> _*Proposal*_
> > >>>
> > >>> I suggest we have the following stricter rules. Anything else is
> > deprecated, logging a warning.
> > >>>
> > >>> * Always include "itemType".
> > >>> * For entity, policy and location: do not include "services:",
> > >>> "brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect
> > >>> exactly one type in the item.
> > >>> * For template, always expect "services:" (even if there is just one
> > >>> thing). This is consistent with the YAML required when deploying an
> > >>> application.
> > >>> * Always include "items", even if there is just one item in it.
> > >>> (reasoning: we do not support "service" versus "services", so why
> > >>> support "item").
> > >>>
> > >>>
> > >>> We should change the following (breaking backwards compatibility,
> > because it's really a bug):
> > >>>
> > >>> * If the itemType differs from the actual type of the item, then
> fail.
> > >>>
> > >>> Aled
> > >>>
> > >>> p.s. I'm in two minds about "item" versus "items": it is simpler with
> > the single item, and having "item" underneath "items" means it's not
> quite
> > like the "services" analogy.
> > >>>
> > >>>
> > >
> >
> > --
>
> Andrew Kennedy ; Founder clocker.io project ; @grkvlt ; Cloudsoft
>
Re: [PROPOSAL] catalog YAML format consistency
Posted by Andrew Kennedy <an...@cloudsoftcorp.com>.
+1
I agree that we need to maintain consistency in our YAML and BOM files, but
not just at the level of Brooklyn item and entity syntax. There should also
be a consistent structural format to the files. For example, when
specifying configuration, we allow items both inside the `brooklyn.config`
map, and outside it. For short examples, missing out `brooklyn.config` is
acceptable, but in general we should use it. There should also be
consistency in ordering the parts of an entity or catalog entry definition,
as well as the formatting of maps, lists and strings.
The following is a suggested style guide, for discussion.
- https://gist.github.com/grkvlt/62ee0ddeea2f4503f82ad25c2f9b31fd
The normative statements are listed here, and the document linked above
contains a conforming YAML fragment showing how they are interpreted.
1. Blueprints MUST place all configuration inside a `brooklyn.config` map,
and MUST use the fully qualified configuration key name
2. Lists MUST be indented properly, to allow IDE folding to work properly
3. Keywords MUST be formatted as `lowerCamel` tokens
4. Sensor, configuration key and section names MUST be formatted as
`lower-hyphen.dot-separated` tokens
5. The preamble for a catalog entry SHOULD contain the following keys,
which MUST appear in this order: version, id, name, description, iconUrl,
origin, license, licenseUrl, publish
6. Entities SHOULD contain the following sections, which MUST appear in
this order: brooklyn.parameters, brooklyn.config, brooklyn.initializers,
brooklyn.enrichers, brooklyn.policies, brooklyn.children
7. Catalog items SHOULD contain the following keys, which MUST appear in
this order: id, name, description, itemType, item
8. Entities and entity specifications SHOULD contain the following keys,
which MUST appear in this order: type, id, name, description, services
9. Names MUST be quoted strings
10. The description value MUST use the multi-line string syntax
11. Parameters SHOULD use the following keys, which MUST appear in this
order: name, label, description, type, default, constraints
Andrew.
On Mon, 20 Jun 2016 at 18:08 Aled Sage <al...@gmail.com> wrote:
> Thanks all,
>
> Alex's suggestion makes a lot of sense. So we should:
>
> 1. agree short-term preferred syntax
> 2. update our docs and examples to *always* use that
> 3. discuss improvements for a more powerful syntax, and the longer term
> bigger long-term overhaul.
>
> It should be trivial to warn someone if they have not included the
> "itemType", so I think we should do that short-term.
>
> ---
> Any more opinions for the preferred syntax?
>
> Aled
>
>
> On 20/06/2016 14:44, Geoff Macartney wrote:
> > +1 for the proposal, and for staging it.
> >
> > I actually quite like the suggestion of making items/item entirely
> consistent (by requiring both). If I have
> >
> > 1 brooklyn.catalog:
> > 2 version: "2.0.0-SNAPSHOT"
> > 3
> > 4 item:
> > 5 type: server
> > 6 id: testy
> > 7 name: Testy McServer
> >
> > and decide for some reason that I need a second item (maybe move one
> here from another file), I can’t just add it below line 7. Instead I have
> to go editing lines 3-7 to add “items:” and change the indentation.
> Sticking to items+item consistently will make this sort of refactoring less
> tedious. Just a thought.
> >
> > Geoff
> >
> >
> >
> >
> > ————————————————————
> > Gnu PGP key - http://is.gd/TTTTuI
> >
> >
> >> On 20 Jun 2016, at 14:17, Svetoslav Neykov <
> svetoslav.neykov@cloudsoftcorp.com> wrote:
> >>
> >> +1 for the proposal.
> >>
> >> I find the current item-items functionality logical. "item" is used in
> leaf items, "items" is used in non-leaf items. Forcing a non-leaf root just
> so we always have "items" is overhead.
> >>
> >> Svet.
> >>
> >>
> >>> On 20.06.2016 г., at 15:47, Aled Sage <al...@gmail.com> wrote:
> >>>
> >>> Hi all,
> >>>
> >>> The YAML format for adding catalog items accepts several different
> ways of defining them. This has led to our examples being inconsistent, our
> code more complicated, and potential confusion for users when they see
> different things that turn out to mean the same.
> >>>
> >>> I think we should standardise on one approach, and deprecate the other
> ways.
> >>>
> >>> ---
> >>>
> >>> _*Current Code*_
> >>>
> >>> An example .bom file is shown below:
> >>>
> >>> brooklyn.catalog:
> >>> items:
> >>> - id: entity1
> >>> version: "1.0.0"
> >>> itemType: entity
> >>> item:
> >>> type: org.apache.brooklyn.entity.machine.MachineEntity
> >>>
> >>> Variants:
> >>>
> >>> * If defining just a single item in the .bom file, you can optionally
> >>> miss out the "items".
> >>> * You can miss out the "itemType" - it will guess at it by trying to
> >>> treat it as an entity, a template, a location or a policy. The
> >>> default is "entity".
> >>> * You can include "services:" for entity or template types, or you can
> >>> miss it out if there is just one entity in the item.
> >>> * Similar to "services:", you can include "brooklyn.policies:" or
> >>> "brooklyn.locations:".
> >>> If itemType is missing, this helps to infer the type. If it does not
> >>> agree with itemType, then we add it as the item type and it will
> >>> fail later.
> >>> * You can define the item metadata at any level - it could be directly
> >>> under "brooklyn.catalog" (in which case it applies to all items), or
> >>> under a specific item (in which case it overrides any more general
> >>> metadata).
> >>>
> >>>
> >>> An example of a .bom for a single item is shown below:
> >>>
> >>> brooklyn.catalog:
> >>> id: entity2
> >>> version: "1.0.0"
> >>> itemType: entity
> >>> item:
> >>> type: org.apache.brooklyn.entity.machine.MachineEntity
> >>>
> >>>
> >>> ---
> >>>
> >>> _*Proposal*_
> >>>
> >>> I suggest we have the following stricter rules. Anything else is
> deprecated, logging a warning.
> >>>
> >>> * Always include "itemType".
> >>> * For entity, policy and location: do not include "services:",
> >>> "brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect
> >>> exactly one type in the item.
> >>> * For template, always expect "services:" (even if there is just one
> >>> thing). This is consistent with the YAML required when deploying an
> >>> application.
> >>> * Always include "items", even if there is just one item in it.
> >>> (reasoning: we do not support "service" versus "services", so why
> >>> support "item").
> >>>
> >>>
> >>> We should change the following (breaking backwards compatibility,
> because it's really a bug):
> >>>
> >>> * If the itemType differs from the actual type of the item, then fail.
> >>>
> >>> Aled
> >>>
> >>> p.s. I'm in two minds about "item" versus "items": it is simpler with
> the single item, and having "item" underneath "items" means it's not quite
> like the "services" analogy.
> >>>
> >>>
> >
>
> --
Andrew Kennedy ; Founder clocker.io project ; @grkvlt ; Cloudsoft
Re: [PROPOSAL] catalog YAML format consistency
Posted by Aled Sage <al...@gmail.com>.
Thanks all,
Alex's suggestion makes a lot of sense. So we should:
1. agree short-term preferred syntax
2. update our docs and examples to *always* use that
3. discuss improvements for a more powerful syntax, and the longer term
bigger long-term overhaul.
It should be trivial to warn someone if they have not included the
"itemType", so I think we should do that short-term.
---
Any more opinions for the preferred syntax?
Aled
On 20/06/2016 14:44, Geoff Macartney wrote:
> +1 for the proposal, and for staging it.
>
> I actually quite like the suggestion of making items/item entirely consistent (by requiring both). If I have
>
> 1 brooklyn.catalog:
> 2 version: "2.0.0-SNAPSHOT"
> 3
> 4 item:
> 5 type: server
> 6 id: testy
> 7 name: Testy McServer
>
> and decide for some reason that I need a second item (maybe move one here from another file), I can\u2019t just add it below line 7. Instead I have to go editing lines 3-7 to add \u201citems:\u201d and change the indentation. Sticking to items+item consistently will make this sort of refactoring less tedious. Just a thought.
>
> Geoff
>
>
>
>
> \u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014
> Gnu PGP key - http://is.gd/TTTTuI
>
>
>> On 20 Jun 2016, at 14:17, Svetoslav Neykov <sv...@cloudsoftcorp.com> wrote:
>>
>> +1 for the proposal.
>>
>> I find the current item-items functionality logical. "item" is used in leaf items, "items" is used in non-leaf items. Forcing a non-leaf root just so we always have "items" is overhead.
>>
>> Svet.
>>
>>
>>> On 20.06.2016 \u0433., at 15:47, Aled Sage <al...@gmail.com> wrote:
>>>
>>> Hi all,
>>>
>>> The YAML format for adding catalog items accepts several different ways of defining them. This has led to our examples being inconsistent, our code more complicated, and potential confusion for users when they see different things that turn out to mean the same.
>>>
>>> I think we should standardise on one approach, and deprecate the other ways.
>>>
>>> ---
>>>
>>> _*Current Code*_
>>>
>>> An example .bom file is shown below:
>>>
>>> brooklyn.catalog:
>>> items:
>>> - id: entity1
>>> version: "1.0.0"
>>> itemType: entity
>>> item:
>>> type: org.apache.brooklyn.entity.machine.MachineEntity
>>>
>>> Variants:
>>>
>>> * If defining just a single item in the .bom file, you can optionally
>>> miss out the "items".
>>> * You can miss out the "itemType" - it will guess at it by trying to
>>> treat it as an entity, a template, a location or a policy. The
>>> default is "entity".
>>> * You can include "services:" for entity or template types, or you can
>>> miss it out if there is just one entity in the item.
>>> * Similar to "services:", you can include "brooklyn.policies:" or
>>> "brooklyn.locations:".
>>> If itemType is missing, this helps to infer the type. If it does not
>>> agree with itemType, then we add it as the item type and it will
>>> fail later.
>>> * You can define the item metadata at any level - it could be directly
>>> under "brooklyn.catalog" (in which case it applies to all items), or
>>> under a specific item (in which case it overrides any more general
>>> metadata).
>>>
>>>
>>> An example of a .bom for a single item is shown below:
>>>
>>> brooklyn.catalog:
>>> id: entity2
>>> version: "1.0.0"
>>> itemType: entity
>>> item:
>>> type: org.apache.brooklyn.entity.machine.MachineEntity
>>>
>>>
>>> ---
>>>
>>> _*Proposal*_
>>>
>>> I suggest we have the following stricter rules. Anything else is deprecated, logging a warning.
>>>
>>> * Always include "itemType".
>>> * For entity, policy and location: do not include "services:",
>>> "brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect
>>> exactly one type in the item.
>>> * For template, always expect "services:" (even if there is just one
>>> thing). This is consistent with the YAML required when deploying an
>>> application.
>>> * Always include "items", even if there is just one item in it.
>>> (reasoning: we do not support "service" versus "services", so why
>>> support "item").
>>>
>>>
>>> We should change the following (breaking backwards compatibility, because it's really a bug):
>>>
>>> * If the itemType differs from the actual type of the item, then fail.
>>>
>>> Aled
>>>
>>> p.s. I'm in two minds about "item" versus "items": it is simpler with the single item, and having "item" underneath "items" means it's not quite like the "services" analogy.
>>>
>>>
>
Re: [PROPOSAL] catalog YAML format consistency
Posted by Geoff Macartney <ge...@cloudsoftcorp.com>.
+1 for the proposal, and for staging it.
I actually quite like the suggestion of making items/item entirely consistent (by requiring both). If I have
1 brooklyn.catalog:
2 version: "2.0.0-SNAPSHOT"
3
4 item:
5 type: server
6 id: testy
7 name: Testy McServer
and decide for some reason that I need a second item (maybe move one here from another file), I can’t just add it below line 7. Instead I have to go editing lines 3-7 to add “items:” and change the indentation. Sticking to items+item consistently will make this sort of refactoring less tedious. Just a thought.
Geoff
————————————————————
Gnu PGP key - http://is.gd/TTTTuI
> On 20 Jun 2016, at 14:17, Svetoslav Neykov <sv...@cloudsoftcorp.com> wrote:
>
> +1 for the proposal.
>
> I find the current item-items functionality logical. "item" is used in leaf items, "items" is used in non-leaf items. Forcing a non-leaf root just so we always have "items" is overhead.
>
> Svet.
>
>
>> On 20.06.2016 г., at 15:47, Aled Sage <al...@gmail.com> wrote:
>>
>> Hi all,
>>
>> The YAML format for adding catalog items accepts several different ways of defining them. This has led to our examples being inconsistent, our code more complicated, and potential confusion for users when they see different things that turn out to mean the same.
>>
>> I think we should standardise on one approach, and deprecate the other ways.
>>
>> ---
>>
>> _*Current Code*_
>>
>> An example .bom file is shown below:
>>
>> brooklyn.catalog:
>> items:
>> - id: entity1
>> version: "1.0.0"
>> itemType: entity
>> item:
>> type: org.apache.brooklyn.entity.machine.MachineEntity
>>
>> Variants:
>>
>> * If defining just a single item in the .bom file, you can optionally
>> miss out the "items".
>> * You can miss out the "itemType" - it will guess at it by trying to
>> treat it as an entity, a template, a location or a policy. The
>> default is "entity".
>> * You can include "services:" for entity or template types, or you can
>> miss it out if there is just one entity in the item.
>> * Similar to "services:", you can include "brooklyn.policies:" or
>> "brooklyn.locations:".
>> If itemType is missing, this helps to infer the type. If it does not
>> agree with itemType, then we add it as the item type and it will
>> fail later.
>> * You can define the item metadata at any level - it could be directly
>> under "brooklyn.catalog" (in which case it applies to all items), or
>> under a specific item (in which case it overrides any more general
>> metadata).
>>
>>
>> An example of a .bom for a single item is shown below:
>>
>> brooklyn.catalog:
>> id: entity2
>> version: "1.0.0"
>> itemType: entity
>> item:
>> type: org.apache.brooklyn.entity.machine.MachineEntity
>>
>>
>> ---
>>
>> _*Proposal*_
>>
>> I suggest we have the following stricter rules. Anything else is deprecated, logging a warning.
>>
>> * Always include "itemType".
>> * For entity, policy and location: do not include "services:",
>> "brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect
>> exactly one type in the item.
>> * For template, always expect "services:" (even if there is just one
>> thing). This is consistent with the YAML required when deploying an
>> application.
>> * Always include "items", even if there is just one item in it.
>> (reasoning: we do not support "service" versus "services", so why
>> support "item").
>>
>>
>> We should change the following (breaking backwards compatibility, because it's really a bug):
>>
>> * If the itemType differs from the actual type of the item, then fail.
>>
>> Aled
>>
>> p.s. I'm in two minds about "item" versus "items": it is simpler with the single item, and having "item" underneath "items" means it's not quite like the "services" analogy.
>>
>>
>
Re: [PROPOSAL] catalog YAML format consistency
Posted by Svetoslav Neykov <sv...@cloudsoftcorp.com>.
+1 for the proposal.
I find the current item-items functionality logical. "item" is used in leaf items, "items" is used in non-leaf items. Forcing a non-leaf root just so we always have "items" is overhead.
Svet.
> On 20.06.2016 г., at 15:47, Aled Sage <al...@gmail.com> wrote:
>
> Hi all,
>
> The YAML format for adding catalog items accepts several different ways of defining them. This has led to our examples being inconsistent, our code more complicated, and potential confusion for users when they see different things that turn out to mean the same.
>
> I think we should standardise on one approach, and deprecate the other ways.
>
> ---
>
> _*Current Code*_
>
> An example .bom file is shown below:
>
> brooklyn.catalog:
> items:
> - id: entity1
> version: "1.0.0"
> itemType: entity
> item:
> type: org.apache.brooklyn.entity.machine.MachineEntity
>
> Variants:
>
> * If defining just a single item in the .bom file, you can optionally
> miss out the "items".
> * You can miss out the "itemType" - it will guess at it by trying to
> treat it as an entity, a template, a location or a policy. The
> default is "entity".
> * You can include "services:" for entity or template types, or you can
> miss it out if there is just one entity in the item.
> * Similar to "services:", you can include "brooklyn.policies:" or
> "brooklyn.locations:".
> If itemType is missing, this helps to infer the type. If it does not
> agree with itemType, then we add it as the item type and it will
> fail later.
> * You can define the item metadata at any level - it could be directly
> under "brooklyn.catalog" (in which case it applies to all items), or
> under a specific item (in which case it overrides any more general
> metadata).
>
>
> An example of a .bom for a single item is shown below:
>
> brooklyn.catalog:
> id: entity2
> version: "1.0.0"
> itemType: entity
> item:
> type: org.apache.brooklyn.entity.machine.MachineEntity
>
>
> ---
>
> _*Proposal*_
>
> I suggest we have the following stricter rules. Anything else is deprecated, logging a warning.
>
> * Always include "itemType".
> * For entity, policy and location: do not include "services:",
> "brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect
> exactly one type in the item.
> * For template, always expect "services:" (even if there is just one
> thing). This is consistent with the YAML required when deploying an
> application.
> * Always include "items", even if there is just one item in it.
> (reasoning: we do not support "service" versus "services", so why
> support "item").
>
>
> We should change the following (breaking backwards compatibility, because it's really a bug):
>
> * If the itemType differs from the actual type of the item, then fail.
>
> Aled
>
> p.s. I'm in two minds about "item" versus "items": it is simpler with the single item, and having "item" underneath "items" means it's not quite like the "services" analogy.
>
>