+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 < [email protected]> 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 <[email protected]> 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 < > > [email protected]> 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 <[email protected]> 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 >
