Skip to content

Latest commit

 

History

History
65 lines (55 loc) · 5.86 KB

event-design-guidelines.md

File metadata and controls

65 lines (55 loc) · 5.86 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.

Benefits and Implications

By following the design guidelines the Eiffel protocol provides a language that gives producers and consumers a common way of understanding and describing the occurrences in the system by defining a contract between them.

Following the guidelines stated, they address the following issues:

  • Protocol variants: By using the protocol it gives the best possible conditions for non-initiated event consumers to make sense of any given set of events.
  • Inconsistency: By providing clear explanations of each member for both producers and consumers it minimizes the risk for both data divergence and inconsistency.
  • Coordination: The Eiffel protocol minimizes coordination efforts between producers and consumers by providing a well-defined specification that the parties can use as a contract.
  • Context: Following the protocol gives each data a clear context to which it belongs.
  • Tight coupling: By using the Eiffel protocol specification it reduces the risk of creating hard connections between producers and consumers. We want to enable adding new consumers without affecting the producers. This then leads to a decoupled system with separation of concerns that enables scalability and maintainability.

When using Eiffel as described it creates a data model based on information nodes and semantics links between these nodes. To read this you will need a tool to aggregate the information.