Reviewing for @cilium/vendor

What is @cilium/vendor?

Team @cilium/vendor is a GitHub team of Cilium contributors who are responsible for maintaining the good state of Go dependencies for Cilium and its related projects by reviewing Pull Requests (PRs) that update files related to dependency declaration:

Each time a contributor opens a PR modifying these files, GitHub automatically assigns one member of the team for review.

Open Pull Requests awaiting reviews from @cilium/vendor are listed here.

To join the team, you must be a Cilium Reviewer. see Cilium’s Contributor Ladder for details on the requirements and the application process.

The team has a dedicated Slack channel in the Cilium Community Slack Workspace named #sig-vendor, which can be used for starting discussions and asking questions in regards to dependency management for Cilium and its related projects.

Reviewing Pull Requests

This section describes some of the processes and expectations for reviewing PRs on behalf of @cilium/vendor. Note that the generic PR review process for Committers still applies, even though it is not specific to dependencies.

Existing Dependencies

Updates to existing dependencies most commonly occur through PRs opened by Renovate, which is a 3rd party service used throughout the Cilium organization. Renovate continually checks repositories for out-of-date dependencies and opens new PRs to update any it finds.

When reviewing PRs that update an existing dependency, members of the @cilium/vendor team are required to ensure that the update does not include any breaking changes or licensing issues. These checks are facilitated via GitHub Action CI workflows, which are triggered by commenting /test within a PR. See CI / GitHub Actions for more information on their use.

New Dependencies

When a new dependency is added as part of a PR, the @cilium/vendor team will be assigned to ensure the new dependency meets the following criteria:

The new dependency must add functionality that is not already provided, in order of preference, within Go’s standard library, an internal package to the project, or an existing dependency.
The functionality provided by the new dependency must be non-trivial to re-implement manually.
The new dependency must be actively maintained, having new commits and/or releases within the past year.
The new dependency must appear to be of generally good quality, having a strong user base, automated testing with high code coverage, and documentation.
The new dependency must have a license which is allowed by the CNCF, as either one of the generally approved licenses or one that is allowed via exception. An automated CI check is in place to help check this requirement, but may need updating as the list of allowable licenses by the CNCF changes and Cilium dependencies change. The source for the license check tool can be found here.

These criteria ensure the long-term success of the project by justifying the inclusion of the new dependency into the project’s codebase.

Cilium Imports

A subset of the repositories the @cilium/vendor team is responsible for import code from cilium/cilium as a dependency. A complication in this relationship is the usage of replace directives in the cilium/cilium go.mod file. Replace directives are only applied to the main module’s go.mod file and do not carry over when imported by another module. This creates the need for replace directives used in the cilium/cilium go.mod file to be synced with any module which imports cilium/cilium as a dependency.

The vendor team is therefore responsible for explicitly discouraging the use of replace directives where possible, due to the extra maintenance burden that they incur.

A replace directive may be used if a required change to an imported library is in the process of being upstreamed and a fork of the upstream library is used as a temporary alternative until the upstream library is released with the required change. The developer introducing the replace directive should ensure that the replace directive will be removed before the next release, even if it involves creating a fork of the upstream library and modifying import statements of the library to point to the fork.

When a replace directive is added into the go.mod file, the vendor team is responsible for the following:

A comment is added above the replace directive in the go.mod file describing the reason it was added.
An issue is created in the project’s repository with a release-blocker label attached, tracking the removal of the replace directive before the next release of the project. The issue should be assigned to the developer who added the replace directive.
Ensuring that replace directives are synced when reviewing PRs which update the version of a cilium/cilium dependency.

If a change that is required to be made to an imported library cannot be upstreamed, the library’s import in the go.mod file should be changed to directly use a fork of the library containing the change, avoiding the need for a replace directive. For an example of this change, see cilium/cilium#27582.