Proposal: Shared maintenance of vendor-specific components

[willarmiros]

• This only affects the JavaScript OpenTelemetry library
• This may affect other libraries, but I would like to get opinions here first

Background

Currently (2/2/21), the opentelemetry-js-contrib repo hosts several NPM packages that allow the core OpenTelemetry SDK to interoperate with popular open-source frameworks and tools. Each package is a pluggable component that OpenTelemetry users can adopt depending on their app's observability setup. There are plugins that can perform automatic instrumentation of libraries like Express, propagators that can change telemetry data to backends like Prometheus, and more. These packages are released to NPM all at once, depending on the latest version of the upstream opentelemetry-js SDK, as outlined in RELEASING.

Problem

Vendors of proprietary monitoring solutions like AWS X-Ray would like to host components like propagators and ID generators that make OpenTelemetry JavaScript interoperable with their software. The maintainers are understandably concerned about increasing scope of maintenance for issues, PRs, and releases relating to new packages.

Proposed Solution

Short Term

Allow adding vendor components to the contrib repo under the condition that issues, PRs, and updating the components for breaking changes between upstream versions is not the responsibility of the maintainers. Instead, it is the responsibility of the initial contributors or other subject matter experts from that vendor. This can be enforced by a CODEOWNERS file, GitHub automation for assigning issues by subtopic, and automated merging of approved PRs for vendor components so the maintainers don't have to. Vendor components failing to adhere to these standards in a reasonable time would be subject to removal from the repo.

All packages, including the vendor-specific packages, would still be released to NPM at once with the naming @opentelemetry/package-name. Releases would still be the sole responsibilities of the maintainers. This would be facilitated by a GitHub Actions workflow that automates the steps in RELEASING, such that the difficulty of releases would not scale with the number of packages. I (@willarmiros) would be able to contribute such a workflow.

NB: The alternative to the proposed release workflow is to decouple the release process for vendor packages from the other packages in the contrib repo. A similar option was considered for .NET contrib, but decided against because it adds too much complexity for OpenTelemetry users to have a monorepo of packages that are versioned differently and potentially pegged to different versions of the upstream SDK.

Long Term

As OpenTelemetry reaches GA status, increases adoption, and more vendors contribute packages it's possible that even with separated maintenance responsibilities hosting all of these packages in the contrib repo will be unsustainable. When the maintainers and vendor package owners agree that such a state has been reached, they can split out the vendor packages into repositories under the open-telemetry org, but that are owned by individual vendors.

This type of approach would need more guidance from the OpenTelemetry governance committee to avoid creating a flood of new repos inconsistently between languages, which is why it is not a short-term solution. But ultimately this approach could resemble the policy for Kubernetes SIG repos.

---

Inspired by open-telemetry/opentelemetry-dotnet-contrib#57
/cc @alolita @anuraaga @srprash

[willarmiros]

As discussed at the JS SIG this morning, the maintainers are comfortable with this approach, so long as the requirements for submitting a repo are made clear in a document along with the conditions for removing a vendor component from the repo if it falls out of maintenance. Next steps are:

1. Submit a PR with such a document
2. Contribute a CD workflow to ease the release process
3. Migrate AWS ID generator and propagator to this repo

[dyladan]

@willarmiros did you ever find out if it is possible to have a codeowner without actual repository write access?

[willarmiros]

@dyladan Unfortunately codeowners must have write access to the repo. However the exact permissions for write access are here and it doesn't allow anything destructive or unreasonable really. My biggest concern would be that it allows you to run workflows, like the CD workflow I'm planning on creating for releases. So we'll need to investigate some way to restrict access to certain workflows.

[weyert]

Hmm, are there plans for Google to move their libraries from their own repo to the contrib-repo? I am a bit confused why AWS packages would be in contrib and other cloud providers once you need to search for.

[dyladan]

This is to provide a framework for any vendors that wish to do so, not just AWS. AWS is just the one motivated to make the push to make this happen.

[weyert]

I just find out about the registry on the website :) Maybe it's worth add a reference to it to this call out: