Skip to content

Added OTIO_CORE 0.14.0 version_manifest. #1415

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.

Sign up for GitHub

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

Merged
merged 5 commits into from
Sep 23, 2022
Merged

Added OTIO_CORE 0.14.0 version_manifest. #1415

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
edf9c5f
Added OTIO_CORE 0.14.0 version_manifest.
jminor Sep 23, 2022
acd6ec1
Adding instructions for runtime downgrading to versioning-schemas.md
jminor Sep 23, 2022
4242b34
Ran make version-map-update
jminor Sep 23, 2022
f535e3a
Removed Test schema from 0.14.0 version manifest.
jminor Sep 23, 2022
47da7d8
Fixed typo and formatting.
jminor Sep 23, 2022
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
29 changes: 29 additions & 0 deletions docs/tutorials/versioning-schemas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,35 @@ otio.adapters.write_to_file(

See the [versioning module](../api/python/opentimelineio.versioning.rst) for more information on accessing these.

## Downgrading at Runtime

If you are using multiple pieces of software built with mismatched versions of OTIO, you may need to configure the newer one(s) to write out OTIO in an older format without recompiling or modifying the software.

You can accomplish this in two ways:
- The `OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL` environment variable can specify a family and version.
- The `otioconvert` utility program can downgrade an OTIO file to an older version.

### OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL Environment Variable

If your software uses OTIO's Python adapter system, then you can set the `OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL` environment variable with a `FAMILY:VERSION` value.
For example, in a *nix shell: `env OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL=OTIO_CORE:0.14.0 my_program`

The `OTIO_CORE` family is pre-populated with the core OTIO schema versions for previous OTIO releases, for example `0.14.0`. If you have custom schema that needs to be downgraded as well, you will need to specify your own family and version mapping, as described above.

### Downgrading with otioconvert

If your software uses OTIO's C++ API, then it does not look for the `OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL` environment variable, but you can convert an OTIO file after it has been created with the `otioconvert` utility.

You can either use a family like this:
```
env OTIO_DEFAULT_TARGET_VERSION_FAMILY_LABEL=OTIO_CORE:0.14.0 otioconvert -i input.otio -o output.otio
```

or you can specify the version mapping for each schema you care about like this:
```
otioconvert -i input.otio -o output.otio -A target_schema_versions="{'Clip':1, 'Timeline':1, 'Marker':2}"
```

## For Developers

During the development of OpenTimelineIO schemas, whether they are in the core or in plugins, it is expected that schemas will change and evolve over time. Here are some processes for doing that.
Expand Down
32 changes: 32 additions & 0 deletions src/opentimelineio/CORE_VERSION_MAP.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,38 @@
namespace opentimelineio { namespace OPENTIMELINEIO_VERSION {

const label_to_schema_version_map CORE_VERSION_MAP {
{ "0.14.0",
Copy link
Member

Choose a reason for hiding this comment

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

Should we also have 0.14.1?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Good question, @JeanChristopheMorinPerso. It would be identical to 0.14.0 right? Should we include every release from now on, or just add one when a schema changes?

Copy link
Member

@JeanChristopheMorinPerso JeanChristopheMorinPerso Sep 26, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

I'm under the impression we don't need 0.14.1 since it only contains bug fixes. But I prefer to ask just in case. Having all versions might make it easier for users to just say "write an OTIO file using that version" without knowing which version contained schema changes. But at the same time it's not like it's really difficult to get this map and figure out pretty quickly which version is required.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Design notes:

  • for this release, I think leaving it like this is fine, since we're backporting it anyway and don't have a strategy
  • I think as a project we should have a discussion. There are two strategies that I can think of off the top of my head:
    • we base everything off the library release version:
      • every release gets an entry
      • +: its straightforward, the only thing anyone needs to know is what version of the library you have
      • -: (potential) we'll end up with a lot of entries that are the same
      • -: (potential) we conflate software release with schema changes (less obvious when things are actually incompatible schema-wise
    • we create a separate "schema version":
      • +: Clear when things actually change
      • +: might be more straightforward for nontechnical end users building pipelines
      • -: adds another version number to track for folks, need to add tools for getting it and possibly recording it, etc.

{
{ "Adapter", 1 },
{ "Clip", 1 },
{ "Composable", 1 },
{ "Composition", 1 },
{ "Effect", 1 },
{ "ExternalReference", 1 },
{ "FreezeFrame", 1 },
{ "Gap", 1 },
{ "GeneratorReference", 1 },
{ "HookScript", 1 },
{ "ImageSequenceReference", 1 },
{ "Item", 1 },
{ "LinearTimeWarp", 1 },
{ "Marker", 2 },
{ "MediaLinker", 1 },
{ "MediaReference", 1 },
{ "MissingReference", 1 },
{ "PluginManifest", 1 },
{ "SchemaDef", 1 },
{ "SerializableCollection", 1 },
{ "SerializableObject", 1 },
{ "SerializableObjectWithMetadata", 1 },
{ "Stack", 1 },
{ "TimeEffect", 1 },
{ "Timeline", 1 },
{ "Track", 1 },
{ "Transition", 1 },
{ "UnknownSchema", 1 },
}
},
{ "0.15.0.dev1",
{
{ "Adapter", 1 },
Expand Down
32 changes: 32 additions & 0 deletions src/opentimelineio/CORE_VERSION_MAP.last.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,38 @@
namespace opentimelineio { namespace OPENTIMELINEIO_VERSION {

const label_to_schema_version_map CORE_VERSION_MAP {
{ "0.14.0",
{
{ "Adapter", 1 },
{ "Clip", 1 },
{ "Composable", 1 },
{ "Composition", 1 },
{ "Effect", 1 },
{ "ExternalReference", 1 },
{ "FreezeFrame", 1 },
{ "Gap", 1 },
{ "GeneratorReference", 1 },
{ "HookScript", 1 },
{ "ImageSequenceReference", 1 },
{ "Item", 1 },
{ "LinearTimeWarp", 1 },
{ "Marker", 2 },
{ "MediaLinker", 1 },
{ "MediaReference", 1 },
{ "MissingReference", 1 },
{ "PluginManifest", 1 },
{ "SchemaDef", 1 },
{ "SerializableCollection", 1 },
{ "SerializableObject", 1 },
{ "SerializableObjectWithMetadata", 1 },
{ "Stack", 1 },
{ "TimeEffect", 1 },
{ "Timeline", 1 },
{ "Track", 1 },
{ "Transition", 1 },
{ "UnknownSchema", 1 },
}
},
// {next}
};

Expand Down