Tool Compatibility Matrix

[scarmuega]

Hi Maintainers!

This issue describes a feature request to augment the available information for the tools section of the Developer Portal. I present this proposal in representation of the Cardano Blockchain Infrastructure Alliance (CBIA). The implementation details are far from being defined. Feedback from maintainers and other members of the CBIA would be greatly appreciated.

Context

The Cardano tool ecosystem is rich and heterogeneous. These are good qualities, but developers face many challenges when trying to orchestrate these tools together to fulfill a particular use-case / application. One of the main challenges is understanding compatibility between the different components.

The Cardano Developer Portal provides a rich index of the tools in the ecosystem. Seasoned Cardano developers rely on this information for updates and new developers use it as reference for their onboarding process.

The motivation behind this initiative is to build on top of the existing work by providing a new dimension of the data listing that focuses on interdependencies, compatibility between tools and compatibility against Cardano protocol features. This data can be used to provide new visualization to support the development process of complex applications.

Schema Changes

Currently, each tool is represented as a JSON object with properties such as "title", "description", "preview", "website", etc. I propose adding a new property named releases to the payload of each tool. This new property will contain an array of objects, where each object holds a description of a released version.

Here's how the enriched JSON payload for the "cardanocli-js" tool could look like:

DISCLAIMER: The data in the example isn't accurate, it's just a sample to facilitate the description of the idea.

{
  "title": "cardanocli-js",
  "description": "A library that wraps the cardano-cli in JavaScript.",
  "preview": "require('./builder-tools/cardanocli-js.png')",
  "website": "https://github.com/Berry-Pool/cardanocli-js",
  "getstarted": "/docs/get-started/cardanocli-js",
  "tags": ["javascript", "sdk"],
  "releases": [
    {
      "version": "3.1.2",
      "latest": true,
      "dependencies": ["cardano-node"],
      "traits": ["babbage", "alonzo", "cip31", "cip32"]
    },
    {
      "version": "3.1.1",
      "dependencies": ["cardano-node"],
      "traits": ["alonzo"]
    }
  ]
}

Each release object contains the following properties:

• version: an opaque string representing the version of the release
• dependencies: an array of required components / tools
• traits: an array of pre-defined tags representing capabilities
• latest: a boolean, when true, it identifies this release as the latest

About Dependencies

The goal of the dependencies array is to provide pointers to other tools available in the same dataset (same JSON). If a tool version doesn't depend on any others, it will be represented as an empty array. The string value of each element in the array should match the title value of the corresponding tool.

These values are NOT meant to become a strict dependency graph as we can find in full-blown package management systems (eg: npm's package.json), but rather an informational field that provides a way to render dependency links on the web based visualization of the portal.

Example:

"dependencies": ["tool_a", "tool_b"]

About Traits

The goal of traits array is to provide indication of broad capabilities that the component supports. In the context of this proposal, traits should be restricted to big-picture concepts of the Cardano protocol, such as hard-forks, eras, CIPs or Plutus versions. If a tool version doesn't have any traits, it will be represented as an empty array.

The list of traits should be predetermined by the maintainers of the portal. Tool developers should conform to the list of well-known traits when adding or updating the metadata for their tool within the context of the portal.

Example:

"traits": ["babbage", "cip31", "plutusV2"]

I rely on feedback and support from CBIA members and maintainers of the portal to compose the initial list of traits.

Visualization Ideas

This proposal doesn't provide any particular visualization of the data, I consider that before reaching that stage we should first gather some data. Nevertheless, here are some ideas to be taken into account for when / if we reach that stage of the project:

Dependency Graph: We could create a visual diagram showing the dependencies between the tools' versions. Each tool version can be a node, and each dependency can be an arrow or a line connecting two nodes. The graph can be interactive to allow developers to better understand the connections between different tool versions.

Trait Matrix: We could implement a matrix in which one axis represents the tools and the other represents the traits. Each cell in the matrix shows the oldest version of the tool that supports the corresponding trait. This feature will enable users to quickly find tool versions that have the traits they need. The matrix could be represented as a table in this way:

	Trait 1	Trait 2	Trait 3
Tool A	v1.0	-	v2.0
Tool B	-	v1.0	v1.5
Tool C	v2.0	-	v3.0

Proposed Roadmap

1. Gather feedback about the proposal from different stakeholders (Developer Portal Maintainers, members of the CBIA, developer community).
2. If approved, reach consensus regarding the new schema of the json and include the pertinent documentation for tool authors.
3. Implement the required changes to the Developer Portal web so that it supports the new schema while maintaining backward compatibility with the previous one (no fancy visualization, just text representation of the new data).
4. Reach out to tool authors requesting that they update their corresponding entries by submitting a PR.
5. Evaluate gathered data and discuss next steps regarding custom visualizations of the new data (eg: trait matrix, dependency graph).

Your input and feedback on this proposal are highly appreciated.

[rdlrt]

I would fully support this idea, it is also a good touch point for those who have added tools and have not touched it again in a while, as the landscape changes vastly every few months - and some tools can become stale if not actively maintained (and an added incentive to keep tools up to date on dev portal for representation)

[katomm]

Thank you Santiago for taking the time to put this feature request together.

[MarvinBertin]

After discussion with @wolf31o2, we have the suggestion to remove the release field and only add dependencies and tags at the root level. The reasoning for this are:

• Tool releases are quite frequent (once a week for many tools), making it a burden for owners to PR releases. This will likely lead to stale and out-of-date metadata
• Once a tool is mature, its dependencies and tag are stable and rarely change. Each release will likely duplicate these fields over and over again.
• If we want to include release versions, it should be done via an automated pipeline that parses release tags directly from github and integrates them into the portal (out-of-scope for this proposal). Similar to tools like https://cardanoupdates.com/. The idea is to minimize the burden of work on tool owners to maintain this Dev Portal and avoid it becoming stale as a result.

Regarding traits, on top of the traits suggested ("babbage", "cip31", "plutusV2"), we could also add major Cardano protocol versions (not specific node versions) like protocol-v8

[OlofBlomqvist]

I think @MarvinBertin and @wolf31o2 is right in that we would very soon see stale data regarding some tools here.

Anyone that actually depend on a specific tool probably would imo. be better of relying on github (or whatever other system used by that tool) for release notifications rather than a statically built site which could be possibly a month behind at all times.

Also, I think if this is implemented, sooner or later people would come to expect dev-portal maintainers to keep these release versions up to date for all tools, which just seems unfair to me.

This would partly be solved by the suggestion of having a way to programatically fetch release info from github, but that also relies on tools using github and not bitbucket, gitlab, etc., or even worse: closed source on some random website.

[Vardominator]

Nice proposal. Some thoughts:

• Let’s assume cardano-node as the axiom, the source of truth, a starting point. It would be incredibly helpful to know at the very least which tools are compatible with which versions of the node. After this is delivered, we can then expand to more complex interdependencies. I think this might help with @rdlrt's point about not being able to actively maintain these dependency updates.
• It seems like this is the consensus, but I would avoid automated pipelines to extract release tags and integrate them for V1. The biggest challenge here is that it would require collaborating directly with all these tools and have their contributors tag things according to these requirements. This will take time.
• One useful way to visualize w/ traits is something similar to a heatmap. The y-axis is the tool name, the x-axis is the trait and the color indicates the version of the tool that supports that trait. Clicking on an individual cell will lead you to the release version page of the Github repo (this would require some additional data in the schema), and clicking on the y-axis ticker would simply lead to the Github or landing page of that tool.
• If you go the “all roads lead to cardano-node” route, you can simply have y-axis be the list of tools, the x-axis be all cardano-node hard fork version and the cell be a check mark indicating that the tool supports that version of the node or not.

[gufmar]

• Let’s assume cardano-node as the axiom, the source of truth, a starting point.

Shouldn't it be more like (Hardfork) era, block- and network-protocol numbers and specifications?

[wolf31o2]

Agreed. The node itself isn't a target for many of us. Libraries such as gOuroboros and Pallas target protocol versions or hard fork functionality. Nodes don't advertise their node version during communication. They advertise their various protocol versions.