Skip to content

Commit

Permalink
[Proposal] A pre-release review process for new major releases of any…
Browse files Browse the repository at this point in the history
… client library

The main idea is that before every major release or the release of a new telemetry type (metrics)
we would like to do a technical and specification conformance review that will ensure consistency
and same "look and feel" for all officially released libraries.

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>
  • Loading branch information
bogdandrutu committed Feb 10, 2021
1 parent c6aa772 commit c64376b
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 0 deletions.
48 changes: 48 additions & 0 deletions releases/new-telemetry-release-process-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Technical Review and Specification Conformance for ${Language}/${TELEMETRY}/${MAJOR_VERSION} library

Technical Committee Sponsor(s): []

Status: [PROPOSAL|REJECTED|APPROVED]

Expected Release Date: []

Spec Compliance Matrix is up to date: [YES|NO]

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/telemetry.
* 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 it is expected to work with the
language maintainers and/or invited language experts to perform this review
process. Language maintainers SHOULD respond to any question during the review
time in a reasonable amount of time to not delay the review process.

It is highly recommended to have at least 2 members of the Technical Committee as sponsors. Any Technical Committee 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 Id)
* Avoid confusions across implementation (e.g same function returns has different behaviors)
* Ensure no experimental features (signals) are part of the main API package.

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.
44 changes: 44 additions & 0 deletions releases/new-telemetry-release-process.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# New Telemetry 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 OpenTelmetry official major release MUST follow the release process
proposed in this document. A "major release" refers to a new version of any
telemetry type (adding a new telemetry type to an already released major version
of the library, or a major version bump for an existing telemetry type) 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 after
the process is started.

To begin the technical and specification compliance review language maintainers
MUST submit a PR and complete this [template](new-telemetry-release-process-template.md).
The name of the file MUST be `technical-specification-review-${language}.md`.

During the review process, breaking changes MAY be needed to comply with the
specification, it is highly recommended to start the process as soon as possible,
but after all features and planned changes are merged.

After the review is approved, it is highly recommended to not make any major
change to the code because that will cause the review to invalidate and the
process needs to be redone.

0 comments on commit c64376b

Please sign in to comment.