Skip to content

Latest commit

 

History

History
36 lines (31 loc) · 4.42 KB

event-design-guidelines.md

File metadata and controls

36 lines (31 loc) · 4.42 KB
Raw

Event Design Guidelines

The design of Eiffel events is governed by the following guidelines:

  • What to communicate is volitional; how to communicate it is not: Users shall never be required to use the entire Eiffel vocabulary to derive benefit. The ability to use only a small subset to solve a particular problem shall always be safeguarded. How to communicate what is to be communicated, however, shall leave minimal room for interpretation.
  • Events as engineering artifact proxies: Eiffel events represent engineering artifacts - items generated in software development – particularly in the realm of continuous integration and delivery. In this way, they are designed to act as proxies and handles of those artifacts.
  • Referencing over duplication: Whenever feasible, do not duplicate what could instead be referenced – both in the case of Eiffel entities and non-Eiffel entities.
  • Event content and delivery are separate concerns: Do not include envelope details in the event contents, and do not introduce technology dependencies into event contents.
  • Do not use variable key names: For purposes of automated validation, analysis and search, custom key names shall be avoided. Consequently, for custom key-value pairs { "key": "customKeyName", "value": "customValue" } shall be used instead of { "customKeyName": "customValue" }.
  • Use industry generic terminology: Wherever possible, rely on industry standards (or at least de-facto standards) rather than internal company specific terminology.
  • Always use explicit semantics: Avoid ambiguous fields left open to interpretation. A key benefit of Eiffel is that it provides a common language for continuous integration and delivery to exchange information – when events are left open to interpretation this benefit is spoiled.
  • Secure technology agnosticity: Eiffel event design shall make no assumptions with regards to underlying infrastructure or tooling.
  • Secure flexibility: Eiffel events shall be designed as descriptive, rather than prescriptive. It shall be assumed that the recipient will react in an intelligent and conducive manner to the information it gathers.
  • Secure scalability: Eiffel events shall be designed so as to serve as natural extension points of continuous integration and delivery systems, where listeners - geographically and organizationally distributed - can hook into the chain of events and build upon it with preserved traceability and semantically unambiguous links.
  • Secure traceability: Eiffel events shall provide semantically unambiguous trace links between multiple types of engineering artifacts - where proxied by Eiffel events by linking to those events, where not through conducive ad-hoc referencing mechanism with a bias for URIs.
  • Be opinionated but open-minded: Eiffel events shall be designed to allow for diverse ways of working, while at the same time encouraging good practice.
  • Information model integrity over reader convenience: Eiffel events are not convenient to read – or to publish – as they require graph traversal in order to derive any meaningful information. Do not work around this by including convenience information (typically duplication). Such measures will never be completely satisfactory. Instead the primary concern of event design is information model integrity; readability and usability is the concern of services built upon that data source.
  • Key names in camelCase: All key names shall use camelCase.
  • Enumerations in CAPS_WITH_UNDERSCORE: All enumerated values shall use CAPS_WITH_UNDERSCORE.
  • Link types are nouns: Link types shall have names that fit the pattern "<target event> is the <source event>'s <link type>", implying that they are nouns that describe the relationship between the source and the target event.