Component Versioning

[jonwinton]

What are the requirements for component versioning?

[jonwinton]

[jonwinton]

• Components schema.yml have an _version property
• On fetch of data + schema the version is checked
• If necessary, the component's data is "upgraded" to the new/current version
• Data is then sent to the model.js and to render

[cruzanmo]

Looks good 👍

[amycheng]

Could you clarify what problems this functionality would solve? Is it for writers who accidentally lose work due to a bad connection or a bad key press? Or is it more for writers working on features who would like access to multiple versions?

Would components have unlimited versions? Are versions created on save? Can end users choose which version they would like to revert to? If not, how does Kiln know which is the correct version? Is it automatically the most recent version?

I'm open to talking about this in person if its easier than using GitHub!

[jonwinton]

@amycheng this is for when a developer updates the schema.yml file for a component, either by:

• Removing a property
• Adding a property
• Renaming a property (which is just an add + remove)

The problem is that when schema's change templates usually do as well. The aim of this is to provide Amphora a way of knowing which version of a component's data we're dealing with and then providing a transformation if some change is necessary to get a component to the most recent version.

• Yes, components have unlimited versions, we're just following semver
• No, a new version is created when a developer increments the _version property in a component's schema
• No, users cannot choose which version. We're not saving each individual version instance of data, a component's instance is still its one source of data. We're just providing a way to keep schema changes and previously saved data in sync.
• Kiln doesn't care about the correct version because transforms are run anytime data is requested and then re-saved as the latest version automatically. Basically, if you're looking at data for a component you can rest assured you're looking at the latest version.

With this method you could actually update ALL your component's instance by just performing a GET to each instance. Otherwise components will be upgraded on the fly as they're requested by users.

[victhevenot]

The Ad Team would LOVE this. Currently right now if we want to ad a new ad unit to an article, we have to back scratch all of the old articles to add a new instance of the ad component to each article. this would allow us to create a new instance on the fly if an article was lacking.

[amycheng]

@jonwinton thnxs for clearing things up. The proposed requirements look fine to me. I'd be interested to learn what the logic for "upgrading" a components data would look look like. Would it also entail comparing the bootstrap.yml?

[jasondecastro]

Yes, to what @vicfriedman said. This would be essential for Ads.
👍

[jonwinton]

@amycheng the only thing that Amphora actually requires for a component is a schema.yml file. Because of this we can't do anything about the bootstrap.yml file.

The upgrade logic would be something like:

• Check _version in the schema.yml
• If saved data _version matches schema _version then send the data along.
• If the versions don't match, figure out which version it's on, figure out which version it should be on, and perform ALL the transforms necessary to get to the current version in order from oldest transform to newest.

So basically, if your component is on version 1.4 and your schema is at 2.2, let's assume there are transforms for: 1.1, 1.6, and 2.1. Since you're component doesn't need the transform for 1.1, we won't run it, but we will run the 1.6 and 2.1 transforms.

[mheiber]

sounds good—would component-upgrading be done through API calls to Amphora (as opposed to Scratch)?

[nelsonpecora]

@mheiber upgrades would just be done (as a low-level thing in amphora-core) when you GET the data (for json, rendering, etc etc)

[jonwinton]

@mheiber but yes, you could make a utility (clay-cli, anyone?) that would just do a GET to every instance of a component.

[jonwinton]

Question appears to be answered, moving to triage.