This repository has been archived by the owner on Dec 6, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 164
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Propose that we move OTEPs into the specification repository.
- Loading branch information
Showing
1 changed file
with
66 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,66 @@ | ||
# 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: | ||
|
||
- 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/` | ||
- `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 specificaiton repository. | ||
- 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. | ||
|
||
## 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 | ||
|
||
What are the important portions of the OTEP process to bring over? Have we missed anything in this description? | ||
|
||
## 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. |