Added notes about versioning OpenTimelineIO-Plugins (#1769)

* Added notes about versioning OpenTimelineIO-Plugins Signed-off-by: Eric Reinecke <[email protected]> --------- Signed-off-by: Eric Reinecke <[email protected]>
AcademySoftwareFoundation · Jun 24, 2024 · 40017d3 · 40017d3
1 parent 0d04b04
commit 40017d3
Showing 1 changed file with 18 additions and 0 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -91,3 +91,21 @@ git push origin mybugfix
 Now your remote branch will have your `mybugfix` branch, which you can now pull request (to OpenTimelineIO's `main` branch) using the github UI.
 
 Please make sure that your pull requests are clean. In other words, address only the issue at hand. Split minor corrections, formatting clean ups, and the like into other PRs. Ensure that new work has coverage in a test. Ensure that any resultant behavioral changes in other parts of the library are called out. Use the rebase and squash git facilities as needed to ensure that the pull request does not contain non-informative remnants of old or superseded work.
+
+## OpenTimelineIO-Plugins Versioning Strategy
+
+OpenTimelineIO provides two PyPI packages:
+
+- `opentimelineio` - the core library and builtin file format support
+- `opentimelineio-plugins` - additional "batteries included" adapters
+
+In short, the rules are:
+
+- `OpenTimelineIO-Plugins` pins to the same `OpenTimelineIO` PyPI version using the `==` constraint - in other words the `OpenTimelineIO-Plugins` version is in lock-step with `OpenTimelineIO`.
+- Each adapter specifies a version constraint against the `OpenTimelineIO` version based on that adapter's requirements.
+- The `OpenTimelineIO-Plugins` project depends on a set of adapters in a floating way, which lets the adapter repos individually deal with their dependency on the core.
+- `OpenTimelineIO-Plugins` is versioned only when plugins are added, removed, or the pinned version of `OpenTimelineIO` is updated.
+
+Keeping `OpenTimelineIO-Plugins` versioning lock-step with `OpenTimelineIO` ensures that version constraints on `OpenTimelineIO-Plugins` will yield the same result as version constraints on `OpenTimelineIO`. For example, installing `OpenTimelineIO-plugins==0.17.0` will guarantee that `OpenTimelineIO` 0.17.0 is installed. Individual adapter version can then be pinned by end-users.
+
+Adapter developers should specify a loose version constraint on `OpenTimelineIO` (e.g. `>=0.17.0`) so that the package manager can discover the adapter version that works best with the desired `OpenTimelineIO` version.