update compatibility doc with support policy

[ekump]

2.0 Upgrade Guide notes
We have updated our compatibility page to include our library support policy.

What does this PR do?
Adds a support policy to our compatibility document and make minor tweaks to compatibility content to conform to the accepted support policy RFC (a non-public doc I can share via private means) to avoid duplicating content.

Motivation:
Better communicate Ruby language version and architecture support for ddtrace.

Additional Notes:
The support policy does not explain how long previous library major versions will be supported. That conversation is ongoing and will be addressed in a separate PR.

How to test the change?

For Datadog employees:

• If this PR touches code that signs or publishes builds or packages, or handles
  credentials of any kind, I've requested a review from @DataDog/security-design-and-guidance.
• This PR doesn't touch any of that.

Unsure? Have a question? Request a review!

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.07%. Comparing base (21f1115) to head (38f5c6e).
Report is 109 commits behind head on 2.0.

Additional details and impacted files

@@            Coverage Diff             @@
##              2.0    #3479      +/-   ##
==========================================
- Coverage   98.07%   98.07%   -0.01%     
==========================================
  Files        1234     1234              
  Lines       71972    71972              
  Branches     3392     3392              
==========================================
- Hits        70587    70586       -1     
- Misses       1385     1386       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[hestonhoffman]

LGTM

[brett0000FF]

Thanks! Approved but I left two minor comments about the links:

• Moving reference links to the end of the page.
• Changing in-line links to reference style links.

[lloeki]

For clarity, I feel there's a need to distinguish between "GA support" in the 2.x line. As is, it sounds like a hypothetical 2.0, 2.1, 2.2 would receive the exact same level of support as a hypothetical 2.3, i.e any bug fix that is landed on a 2.3.y are going to be all backported to 2.0.y, 2.1.y, 2.2.y.

In turn, the same applies to 1.x, we have 1.0-1.15 but it's not like we're going to backport 1.15.y critical/security fixes to 1.0.y-1.14.y.

AIUI in both cases fixes only land for the latest minor, bumping its patch (this is given the expectation of backwards compatibility within a major, which should allow any x.y version to be updated to a x.z version without breakage)

[ekump]

That's fair. What do you think is the best way to communicate that this only applies to the latest minor versions? I could change the column header Gem Version to Gem Major Version and drop the .x?

We could also add a sentence in the text above the table along the lines of Respective levels of support for major versions are provided via the latest minor versions. Datadog will generally not backport changes to previous minor versions via patch releases. For example if 2.3 is the latest version of 2.x, changes will not be backported to 2.2, 2.1, etcetera.

[delner]

I like the explicit nature of the expanded table, showing each version. You could collapse these into ranges where the info is repetitive e.g. 2.1-2.4. But that's a minor issue.

[ekump]

@delner As I understand it, this table is supposed to convey the level of support available in major versions. I agree with @lloeki that it's unclear in its current form that normally, that support is provided via new minor releases. Would listing every single version of the library help convey this information better?

[lloeki]

The annoying part with explicitly listing versions including minor is that we'd have to update the doc on every release, which would be annoying.

Gem Major Version

That would have been my suggestion, but it also makes it less explicit that only the latest major is supported.

Counterpoint though: that's what node does and it seems fine.

I think a visual representation such as this one would reaaaally drive the point home.

[ivoanjo]

Left a few notes!

[ivoanjo]

Should we add some statement regarding Linux on other architectures? (Dev environments only? Talk to us?)

[ekump]

I don't think we should mark any architectures as dev-only if we don't have some sort of CI in place for it. I could add a sentence below the table that says:

Need linux support for a CPU architecture not listed? Contact our customer support team for special requests.

[ivoanjo]

Seems reasonable!

[lloeki]

I don't know what the status for profiling/libdatadog is, but for libddwaf it goes like this:

a) We have binaries for supported platofrms
b) libddwaf is able to be compiled on basically any platform, the ruby platform gem can† do that.

If customers figure out a way to have it build (which is essentially having a C++ compiler + CMake when gem install happens) then they can have ASM work on ppc64le, RISC-V, FreeBSD, Solaris, what have you. These would of course be unsupported, but by and large they would work basically OOTB.

† It's not done yet but I'm planning to do it to support the people that use force_ruby_platform on supported platforms. The above will come as a consequence of that.

[ivoanjo]

I don't know what the status for profiling/libdatadog is, but for libddwaf it goes like this:

The current status is we're shipping libdatadog binaries for [x86-64, arm64] x [linux glibc, linux musl], so that's what profiler supports out of the box.

(It's undocumented, but if you can manually compile libdatadog to more platforms, and profiler does usually work on them as well).

---

Having said that, @lloeki I think @ekump has a reasonable point about the difference between "we have binaries for obscure platforms" and "we're actively testing and supporting them". If we're not testing on Solaris, and would struggle if someone came to us with a bug that only triggered on Solaris, should we state we support Solaris?

I think it's OK to have a "best-effort, come talk to us if this really important to you" tier, but I think it makes sense to be clear in this table about how much effort we would spend on issues for these platforms.

[lloeki]

If we're not testing on Solaris, and would struggle if someone came to us with a bug that only triggered on Solaris, should we state we support Solaris?

I agree, hence why I said these fall under "unsupported".

The conundrum I have is that once I add support for the ruby platform to properly support {x86_64,aarch64}-linux-{gnu,musl} the other platforms are going to start working but we don't want ambiguity as to whether they're supported through the fact that the ruby platform is.

I think it's OK to have a "best-effort, come talk to us if this really important to you" tier, but I think it makes sense to be clear in this table about how much effort we would spend on issues for these platforms.

I like the "best effort" angle, especially if it encourages external contributions. And I agree, this is all about clarity in communicating the effort we are able to expend (both in terms of human resources e.g dev/debug time and technical resources e.g CI).

[ivoanjo]

👍 LGTM

[delner]

Some minor suggestions/concurrence with some other suggestions, but the bulk of this looks good. My only other suggestion would be to strike APM from where we see Datadog APM for Ruby, given this library contains much more than just APM.

[lloeki]

I don't know what the status for profiling/libdatadog is, but for libddwaf it goes like this:

a) We have binaries for supported platofrms
b) libddwaf is able to be compiled on basically any platform, the ruby platform gem can† do that.

If customers figure out a way to have it build (which is essentially having a C++ compiler + CMake when gem install happens) then they can have ASM work on ppc64le, RISC-V, FreeBSD, Solaris, what have you. These would of course be unsupported, but by and large they would work basically OOTB.

† It's not done yet but I'm planning to do it to support the people that use force_ruby_platform on supported platforms. The above will come as a consequence of that.