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

RFC: IR format versioning #258

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
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
62 changes: 62 additions & 0 deletions docs/rfc/007-ir-format-versioning.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# RFC: IR format versioning

18 Mar 2019

_In order to make changes to the IR, we need to decide on a versioning scheme that best communicates the impact of our changes, as this will likely have an impact on how other tools that interact with the IR are versioned. This RFC proposes a single digit versioning scheme, where all IR changes increment this number._

## Proposal

Today, all IR documents start with:

```js
{
"version" : 1,
...
}
```

This RFC proposes that _all_ changes to the IR format increment this number:

```js
{
"version" : 2,
...
}
```

The implications of this are that:

- **consumers detect unsupported features** - A conjure generator which is feature complete (i.e. supports all concepts in the current IR) can immediately detect if it is passed an IR document that may contain unsupported features. For example, a conjure-docs generator which converts IRv1 -> HTML could warn users if they tried to invoke it with an IRv2 document, as important information contained in the IRv2 document might not be fully captured in the resulting HTML (e.g. if IRv2 introduced new ways of marking fields as deprecated, the resulting HTML might still advertise them as non-deprecated)
- **consumers do best-effort generation** - when parsing an IR document, consumers should attempt to run even if the IR format version is higher or lower than they expected (as some of the IR changes might be benign or irrelevant). The version number is then used to present a helpful user-facing message if generation failed.

This single digit versioning scheme is mainly justified by considering the main alternative, a `major.minor` scheme to try and differentiate breaking and non-breaking changes:

## Alternative considered: `major.minor` versioning

Possible changes to the IR format can only be modelled as two categories: semantic additions or restrictions.

- **additive changes** - extend the language with new functionality, allow expressing new concepts. All previously valid IR files would still be considered valid files in the new format.
- **restrictive changes** - remove some language concept that was previously supported, or introduce some new stricter validation some previously valid IR files would no longer be considered valid.

(If the behaviour of language feature is changed, this can be modelled as removing the old feature and adding a new one)

There are also two types of interaction with the IR: producers and consumers.

- **producers** - API authors who write conjure YML and thereby produce (and publish) Conjure IR
- **consumers** - conjure generators consume IR and emit language-specific code

A contradiction arises because a major.minor versioning scheme can only really satisfy IR consumers or IR producers, it can't meaningfully communicate breaks to both:


  | Additive IR Change | Restrictive IR Change |
-------------------------- | ---------------------- | --------------------- |
**Producers** | Don't care (minor rev) | Breaking (major rev)
**Consumers** | Breaking (major rev) | Don't care (minor rev)

Producers don't care about additive changes to the IR because they can keep taking upgrades whether the new features are relevant to them or not. Producers do care about restrictive changes to the IR as this could potentially make their current API definitions invalid, thereby even . This suggests additive changes should increment minor, and restrictive should increment major.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thereby even .

I think we're missing some words


However, consumers have the opposite perspective. Consumers don't care about restrictive changes to the IR - if some Conjure feature was banned, the same generators could keep running - they would just happen to no longer encounter certain categories of input. Additive changes on the other hand do require changes to generators in order to be supported - these can therefore be considered breaking.

## Draft releases

In order to allow iterating on an unreleased or experimental IR format, an additional 'draft' field could be defined in a dedicated RFC.