Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

event-protocol: document decisions from meetup #159

Merged
merged 1 commit into from
Mar 18, 2017
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 17 additions & 18 deletions event-protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,18 +85,6 @@ Example (Java stack trace):
[snippet](examples/events/004_attachment-stacktrace.json)
```

### Cucumber-specific attachments

Cucumber-specific events such as "a step definition was found for this step" or
"a step failed" could be represented as attachments with special media types, for example:

* `application/vnd.cucumber.step.match+json`, information about the match such as arguments, stepdef line number etc.
* `text/vnd.cucumber.step.status+plain`, status of a failing step (passed, undefined, pending, failed, skipped)

They could also be represented as distinct events with a separate type. The Cucumber team
is currently undecided on this. Once consumers evolve we will have more information about
the tradeoffs of each design. See the [contributing](#contributing) section for details.

## Implementation

* Cucumber events are formatted as [Newline Delimited JSON](http://ndjson.org)
Expand All @@ -108,26 +96,37 @@ the tradeoffs of each design. See the [contributing](#contributing) section for

### Philosophy

As the event specification evolves to support a richer set of events there are some
As this event protocol specification evolves to support a richer set of events there are some
key principles to consider:

#### Extend, don't ammend

Any consumer of the event protocol that also emits the protocol must faithfully emit all events it receives as input. It can, of course, add extra events to the output stream.

#### Small, specialised events

To keep the protocol flexible, we encourage having many different specialised events, rather than trying to use generic messages for broad purposes.

#### File format agnostic

While Gherkin is currently the only file format that will be used in `source`
events, no events should assume that all files will be Gherkin documents. This
allows for alternative document formats in the future.

#### Errors are attachments
#### Versioning will be per-event

When we need to revise the protocol, this will take one of three forms:

1) Changing the schema for an existing event
2) Adding a new event
3) Deprecating an event we no longer want to support

When an error occurs, that's just an attachment to a `source` file, with a [special
media type](#event-attachment). This goes for parse errors, execution errors/exceptions, linting
errors etc.
We'll manage this by adding a version to a specific event, where needed. For now there will be no version numbers. The overall protocol will not be versioned.

## Event order {#order}

There are a few constraints about the order of events:

* The first event must be [start](#start)
* A [source](#event-source) event must be received before any
[attachment](#event-attachment) events referring to it

Expand Down