Skip to content
This repository has been archived by the owner on Dec 6, 2024. It is now read-only.

Propose that we move OTEPs into the specification repository. #266

Merged
merged 6 commits into from
Oct 22, 2024
Merged
Changes from all 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
68 changes: 68 additions & 0 deletions text/0266-move-oteps-to-spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Move OTEPS to the Specification repository

Let's move OTEP documentation and PRs back into the github.com/open-telemetry/opentelemetry-specification repository.

## Motivation

Moving OTEPs back into the specification solves two main issues:

- Maintaining its tooling infrastructure (currently woefully out of date)
- Bringing it into the existing triage and voting process currently within the
Specification.

## Explanation

Originally, OTEPs were kept as a separate repository to keep disjoint/disruptive designs as a separate repository. There are a few differences between a normal PR and an OTEP:
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

- OTEPs are expected to be directional and subject to change when actually entered into the specification.
- OTEPs require more approvals than specification PRs
- OTEPs have different PR worklfows (whether due to accidental omission or conscious decision), e.g. staleness checks, linting.

As OpenTelemetry is stabilizing, the need for OTEPs to live outside the specification is growing less, and we face challenges like:

- Keeping OTEP tooling up to date
- Advertising the repositories existence
- New contributors to OpenTelemetry often can't find recorded decision that exist in OTEPs.
- Getting reviews from folks used to checking the Specification repository, but not the less-frequently-worked-on OTEP repository.

To solve these, let's move OTEPs into a directory within the [specification repository](github.com/open-telemetry/opentelemetry-specification).
We would also update all tooling and expected reviews to match existing standards for OTEPs. Given the maintainers of OTEPs are the same as
maintainers of the specification, this should not change the bar for acceptance.

## Internal details

The following changes would occur:

- The following files would be moved to the specification repo:
- `text/` directory -> `oteps/text/`
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
- `0000-template.md` -> `oteps/0000-template.md`
- Update the specification `Makefile` to include linting, spell checking, link checking and TOC-ing the oteps directory.
- A one-time cleanup of OTEP markdown upon import to the specification repository.
- Close existing OTEP PRs and ask folks to reopen against the specification repository.
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
- New labels within the specification repository to tag OTEPs, including automation to set these on PR open.
- Updating contributing guidelines to include a section about OTEPs.
- Add `oteps/README.md` file outlining that OTEPS are not normative and part of enhancement proposal process.
- Add disclaimer to the header of every OTEP that the contents are not normative and part of the enhancement proposal process.

## Trade-offs and mitigations

Moving into the specification repository DOES mean that we would have a directory with a different quality bar and, somewhat, process than the rest of the repository.
This can be mitigated through the use of clear, vibrant labels for OTEPS, and updating process guidelines for the specification repository to retain the important
aspects of the current OTEP status.

## Prior art and alternatives

OTEPs were originally based on common enhancement proposal processes in other ecosystems, where enhancements live outside core repositories and follow a more rigorous criteria and evaluation. We are finding this
problematic for OpenTelemetry for reasons discussed above. Additionally, unlike many other ecosystems where enhancement/design is kept separate from core code, OpenTelemetry *already* keeps its design separate
form core code via the Specification vs. implementation repositories. Unlike these other OSS projects, our Specification generally requires rigorous discussion, design and prototyping prior to acceptance. Even
after acceptance into the specification, work is still required for improvements to roll out to the ecosystem. Effectively: The OpenTelemetry specification has no such thing as a "small" change: There are only medium changes that appear small, but would be enhancements in other proejcts or large changes that require an OTEP.

## Open questions
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

What are the important portions of the OTEP process to bring over? Have we missed anything in this description?
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

## Future possibilities

In the future, we could figure out how to make OTEPs more searchable, discoverable and highlighted within the opentelemetry.io website.

Additionally, we can look at extending staleness deadlines for OTEP labeled PRs.