From 2b3a7d9b7441d0348a5d93d8d42862b60bca4b9f Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Fri, 30 Aug 2024 13:01:16 -0400 Subject: [PATCH 1/5] Propose that we move OTEPs into the specification repository. --- text/????-move-oteps-to-spec.md | 66 +++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 text/????-move-oteps-to-spec.md diff --git a/text/????-move-oteps-to-spec.md b/text/????-move-oteps-to-spec.md new file mode 100644 index 000000000..4b433fdba --- /dev/null +++ b/text/????-move-oteps-to-spec.md @@ -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. \ No newline at end of file From c76209dccd6b410fdeab993afa20c778cfc73b5c Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Fri, 30 Aug 2024 13:02:35 -0400 Subject: [PATCH 2/5] move to PR number. --- text/{????-move-oteps-to-spec.md => 0266-move-oteps-to-spec.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename text/{????-move-oteps-to-spec.md => 0266-move-oteps-to-spec.md} (100%) diff --git a/text/????-move-oteps-to-spec.md b/text/0266-move-oteps-to-spec.md similarity index 100% rename from text/????-move-oteps-to-spec.md rename to text/0266-move-oteps-to-spec.md From 8d9411fbad7eb6d408649db6a42680f7226e0bde Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Fri, 30 Aug 2024 13:04:37 -0400 Subject: [PATCH 3/5] Fix lint issues. --- text/0266-move-oteps-to-spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0266-move-oteps-to-spec.md b/text/0266-move-oteps-to-spec.md index 4b433fdba..60260b511 100644 --- a/text/0266-move-oteps-to-spec.md +++ b/text/0266-move-oteps-to-spec.md @@ -21,7 +21,7 @@ Originally, OTEPs were kept as a separate repository to keep disjoint/disruptive 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 +- 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. @@ -38,7 +38,7 @@ The following changes would occur: - `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. +- Close existing OTEP PRs and ask folks to reopen against the specification 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. @@ -63,4 +63,4 @@ What are the important portions of the OTEP process to bring over? Have we misse 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. \ No newline at end of file +Additionally, we can look at extending staleness deadlines for OTEP labeled PRs. From 4a77ad63b138adcc48912ca99208cfd693967652 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Fri, 30 Aug 2024 15:26:14 -0400 Subject: [PATCH 4/5] Address concerns on normative language in oteps. --- text/0266-move-oteps-to-spec.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0266-move-oteps-to-spec.md b/text/0266-move-oteps-to-spec.md index 60260b511..375ca19b7 100644 --- a/text/0266-move-oteps-to-spec.md +++ b/text/0266-move-oteps-to-spec.md @@ -41,6 +41,8 @@ The following changes would occur: - Close existing OTEP PRs and ask folks to reopen against the specification 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. +- 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 From e1ee1b8a8b0209b13d8c5191bb46d627dc6f9167 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Fri, 30 Aug 2024 15:26:37 -0400 Subject: [PATCH 5/5] Remove . in header. --- text/0266-move-oteps-to-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0266-move-oteps-to-spec.md b/text/0266-move-oteps-to-spec.md index 375ca19b7..997bf501a 100644 --- a/text/0266-move-oteps-to-spec.md +++ b/text/0266-move-oteps-to-spec.md @@ -1,4 +1,4 @@ -# Move OTEPS to the Specification repository. +# Move OTEPS to the Specification repository Let's move OTEP documentation and PRs back into the github.com/open-telemetry/opentelemetry-specification repository.