Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Proposal] A pre-release review process for new major releases of any client library #1418

Closed
Closed
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,3 +193,6 @@ on each other), the owner should try to get people aligned by:
If none of the above worked and the PR has been stuck for more than 2 weeks, the
owner should bring it to the [OpenTelemetry Specification SIG
meeting](https://github.com/open-telemetry/community#cross-language-specification).

New signal release reviews are subject to different rules that and do not follow
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
the above process. For that please see [here](releases/new-signal-release-process.md).
55 changes: 55 additions & 0 deletions releases/new-signal-release-process-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Technical Review and Specification Conformance for ${LANGUAGE}/${SIGNAL}/${MAJOR_VERSION} library

Technical Committee Sponsor(s): []
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the process by which Technical committee sponsors identified?

  1. Are they assigned or chosen by the Lang maintainers?
  2. This is going to heavily depend on TC member(s) availability during the next 'n' days. Will the TC triage incoming review requests and assign members?
  3. What is the expectation during the review window? - Will issues be added to the review template PR as found or at the end of the review window. We should avoid a whole bunch of issues identified and shared with the Language maintainers in one fell swoop at the end of the review period, which would cause delays.


Expected Release Date: []

Expected Version Number: []
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved

Spec Compliance Matrix is up to date: [Permanent link to the matrix]
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved

Versioning And Stability Document: [Link to version document]

Public Code Documentation: [Link to godoc, javadoc, etc.]

Public Examples: [Link to couple of official usage examples]

Discovered Issues: [List of filed issues by the TC members during the review process]

## TODOs

This section must be deleted when the PR for starting the review is opened,
but it contains a list of important TODOs that maintainers MUST do before starting the process.

The Language Maintainers MUST:

* Prior to starting the review, update the
[compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md)
for that language/signal.
* Each language implementation MUST follow
[the versioning and stability requirements](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md)
and prepare the public documentation about the versioning and stability guarantees.
* Work with a Technical Committee Sponsor(s) during review. The Technical
Committee members are not language experts, and are expected to work with the
language maintainers and/or invited language experts to perform this review
process. Language maintainers SHOULD respond to any question/issue
(github issues, github discussions, gitter, or comments in the review PR)
during the review time in a reasonable amount of time to not delay the review
process (ideally 1 business day).

It is highly recommended to have at least 2 members of the Technical Committee
as sponsors. Any Technical Committee member can be a sponsor, and any Technical
Committee member can provide feedback during the review process.

Technical Committee Sponsor(s) MUST:

* Do the due diligence and review the public documentation and examples, and
ensure specification conformance.
* Ensure conformance with the versioning and stability document.
* Ensure consistent names across implementations (e.g. TraceId vs GlobalId)
* Avoid confusions across implementation (e.g same public API has different behaviors)
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
* Ensure no experimental features (signals) are part of the released packages (e.g. api, sdk, etc.).
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved

The OpenTelemetry Technical Committee MUST attend one of the language SIG
meetings and have a public discussion with the language maintainers to discuss
any issues found during the review process.
46 changes: 46 additions & 0 deletions releases/new-signal-release-process.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# New Signal Release Process

This document defines the release requirements and process followed by the
OpenTelemetry libraries, along with the rules and procedures for meeting those
requirements.

In this document, the terms "OpenTelemetry" and "language implementations" both
specifically refer to the OpenTelemetry client libraries. These terms do not
refer to the specification or the Collector in this document.

Every OpenTelemetry official major release MUST follow the release process
proposed in this document. A "major release" refers to a new version of any
[signal](../specification/glossary.md#signals) (adding a new signal to an
already released major version of the library, or a major version bump for an
existing released signal) for OpenTelemetry client libraries.

The OpenTelemetry [Technical Committee](https://github.com/open-telemetry/community/blob/main/tech-committee-charter.md) (with guidance from language maintainers) is responsible to setup release dates
and ensure quality standards of the official releases
[here](https://github.com/open-telemetry/community/blob/main/tech-committee-charter.md#responsibilities-of-the-technical-committee).

To graduate the release process, each language implementation MUST do:

* Technical and Specification Compliance Review

The OpenTelemetry Technical Committee reserves the right to change and improve
this process during time based on the prior experiences.

## Technical and Specification Compliance Review

The OpenTelemetry [Technical Committee](https://github.com/open-telemetry/community/blob/main/tech-committee-charter.md)
commits to ensure that every decision will be made in less than 14 days (2 weeks)
after the process is started.

To begin the technical and specification compliance review language maintainers
MUST submit a PR and complete this [template](new-signal-release-process-template.md).
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
The name of the file MUST be `release-review-${LANGUAGE}-${SIGNAL}-v${MAJOR_VERSION}.md`,
and the title of the PR MUST be `Release review for ${LANGUAGE}/${SIGNAL}/v${MAJOR_VERSION}`.

During the review process, breaking changes related to the new signal MAY be
needed to comply with the specification, it is highly recommended to start
the process as soon as possible (a good time would be immediately after the
release of the first RC), but after all features and planned changes are merged.

After the review is approved, it is highly recommended to not make any major
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
change to the public API because that will cause the review to invalidate and the
process needs to be redone.