Add OL compatibility table (MarquezProject#2493)

* Add OL compatibility table Signed-off-by: wslulciuc <[email protected]> * Add info on OL compatibility Signed-off-by: wslulciuc <[email protected]> * continued: Add info on OL compatibility Signed-off-by: wslulciuc <[email protected]> * Update `RELEASING.md` with compatibility guidelines Signed-off-by: wslulciuc <[email protected]> * continued: Add info on OL compatibility Signed-off-by: wslulciuc <[email protected]> * Pin to OL 1-0-5 Signed-off-by: wslulciuc <[email protected]> * Fix typo Signed-off-by: wslulciuc <[email protected]> --------- Signed-off-by: wslulciuc <[email protected]>
algorithmy1 · May 31, 2023 · 4fa6501 · 4fa6501
1 parent 94b11f4
commit 4fa6501
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -58,7 +58,7 @@ You can open [http:https://localhost:3000](http:https://localhost:3000) to begin exploring t
 
 **`HTTP API`**
 
-The Marquez [HTTP API](https://marquezproject.github.io/marquez/openapi.html) listens on port `5000` for all calls and port `5001` for the admin interface. The admin interface exposes helpful endpoints like `/healthcheck` and `/metrics`. To verify the HTTP API server is running and listening on `localhost`, browse to [http:https://localhost:5001](http:https://localhost:5001). To begin collecting lineage metadata as OpenLineage events, use the [LineageAPI](https://marquezproject.github.io/marquez/openapi.html#tag/Lineage/paths/~1lineage/post) or an OpenLineage [integration](https://openlineage.io/integration).
+The Marquez [HTTP API](https://marquezproject.github.io/marquez/openapi.html) listens on port `5000` for all calls and port `5001` for the admin interface. The admin interface exposes helpful endpoints like `/healthcheck` and `/metrics`. To verify the HTTP API server is running and listening on `localhost`, browse to [http:https://localhost:5001](http:https://localhost:5001). To begin collecting lineage metadata as OpenLineage events, use the [LineageAPI](https://marquezproject.github.io/marquez/openapi.html#tag/Lineage/paths/~1lineage/post) or an OpenLineage [integration](https://openlineage.io/docs/integrations/about).
 
 > **Note:** By default, the HTTP API does not require any form of authentication or authorization.
 
@@ -72,6 +72,20 @@ We invite everyone to help us improve and keep documentation up to date. Documen
 
 > **Note:** To begin collecting metadata with Marquez, follow our [quickstart](https://marquezproject.github.io/marquez/quickstart.html) guide. Below you will find the steps to get up and running from source.
 
+## Versions and OpenLineage Compatibility
+
+Versions of Marquez are compatible with OpenLineage unless noted otherwise. We ensure backward compatibility with a newer version of Marquez by recording events with an older OpenLineage specification version. **We strongly recommend understanding how the OpenLineage specification is** [versioned](https://github.com/OpenLineage/OpenLineage/blob/main/spec/Versioning.md) **and published**.
+
+| **Marquez** | **OpenLineage** | **Status** |
+|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------|---------------|
+| [`UNRELEASED`](https://github.com/OpenLineage/OpenLineage/blob/main/CHANGELOG.md#unreleased) | [`1-0-5`](https://openlineage.io/spec/1-0-5/OpenLineage.json) | `CURRENT` |
+| [`0.34.0`](https://github.com/MarquezProject/marquez/blob/0.34.0/CHANGELOG.md#0340---2023-05-18) | [`1-0-5`](https://openlineage.io/spec/1-0-5/OpenLineage.json) | `RECOMMENDED` |
+| [`0.33.0`](https://github.com/MarquezProject/marquez/blob/0.33.0/CHANGELOG.md#0330---2023-04-19) | [`1-0-5`](https://openlineage.io/spec/1-0-0/OpenLineage.json) | `MAINTENANCE` |
+
+> **Note:** The [`openlineage-python`](https://pypi.org/project/openlineage-python) and [`openlineage-java`](https://central.sonatype.com/artifact/io.openlineage/openlineage-java) libraries will a higher version than the OpenLineage [specification](https://github.com/OpenLineage/OpenLineage/tree/main/spec) as they have different version requirements.
+
+We currently maintain three categories of compatibility: `CURRENT`, `RECOMMENDED`, and `MAINTENANCE`. When a new version of Marquez is released, it's marked as `RECOMMENDED`, while the previous version enters `MAINTENANCE` mode (which gets bug fixes whenever possible). The unreleased version of Marquez is marked `CURRENT` and does not come with any guarantees, but is assumed to remain compatible with OpenLineage, although surprises happen and there maybe rare exceptions.
+
 ## Modules
 
 Marquez uses a _multi_-project structure and contains the following modules:
@@ -158,5 +172,5 @@ See [CONTRIBUTING.md](https://github.com/MarquezProject/marquez/blob/main/CONTRI
 If you discover a vulnerability in the project, please open an issue and attach the "security" label.
 
 ----
-SPDX-License-Identifier: Apache-2.0 
-Copyright 2018-2023 contributors to the Marquez project.
+SPDX-License-Identifier: Apache-2.0
+Copyright 2018-2023 contributors to the Marquez project.
diff --git a/RELEASING.md b/RELEASING.md
@@ -1,19 +1,20 @@
 # Releasing
 
 1. Update [`CHANGELOG.md`](CHANGELOG.md)
-2. Make sure you've installed the required dependencies (see [`new-version.sh`](new-version.sh)).
-3. Tag the release and prepare for the next version with:
+2. Update [_Versions and OpenLineage Compatibility_](https://github.com/MarquezProject/marquez/blob/main/README.md#versions-and-openlineage-compatibility) following compatibility guidelines
+3. Make sure you've installed the required dependencies (see [`new-version.sh`](new-version.sh)).
+4. Tag the release and prepare for the next version with:
 
  ```bash
  $ ./new-version.sh --release-version X.Y.Z --next-version X.Y.Z --no-push
  ```
 
  > **Tip:** Use `--help` to see script usage
 
-4. Push the tag with the command supplied by the script.
-5. Visit [CI](https://app.circleci.com/pipelines/github/MarquezProject/marquez?branch=main) to see the progress of the release! :rocket:
-6. Visit [sonatype](https://oss.sonatype.org) to promote _java_ artifacts
-7. Draft a [new release](https://github.com/MarquezProject/marquez/releases/new) using the release notes for `X.Y.Z` in **step 1** as the release description:
+5. Push the tag with the command supplied by the script.
+6. Visit [CI](https://app.circleci.com/pipelines/github/MarquezProject/marquez?branch=main) to see the progress of the release! :rocket:
+7. Visit [sonatype](https://oss.sonatype.org) to promote _java_ artifacts
+8. Draft a [new release](https://github.com/MarquezProject/marquez/releases/new) using the release notes for `X.Y.Z` in **step 1** as the release description:
 
  ![](./docs/assets/images/new-release.png)
 
@@ -36,5 +37,5 @@ If the proposed release receives no +1s in two days, it is not authorized and th
 Once a release is authorized, it will be initiated within two business days. Releases will not be made on a Friday unless doing so will address an important defect, an issue with project infrastructure, or a security vulnerability.
 
 ----
-SPDX-License-Identifier: Apache-2.0 
-Copyright 2018-2023 contributors to the Marquez project.
+SPDX-License-Identifier: Apache-2.0
+Copyright 2018-2023 contributors to the Marquez project.