Skip to content

Commit 6b82113

Browse files
committed
Add README and template.
1 parent 02531b0 commit 6b82113

File tree

2 files changed

+129
-0
lines changed

2 files changed

+129
-0
lines changed

oteps/0000-template.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Replace this with your awesome OTEP title
2+
3+
Short (one sentence) summary, e.g., something that would be appropriate for a [CHANGELOG](https://keepachangelog.com/) or release notes.
4+
5+
## Motivation
6+
7+
Why should we make this change? What new value would it bring? What use cases does it enable?
8+
9+
## Explanation
10+
11+
Explain the proposed change as though it was already implemented and you were explaining it to a user. Depending on which layer the proposal addresses, the "user" may vary, or there may even be multiple.
12+
13+
We encourage you to use examples, diagrams, or whatever else makes the most sense!
14+
15+
## Internal details
16+
17+
From a technical perspective, how do you propose accomplishing the proposal? In particular, please explain:
18+
19+
* How the change would impact and interact with existing functionality
20+
* Likely error modes (and how to handle them)
21+
* Corner cases (and how to handle them)
22+
23+
While you do not need to prescribe a particular implementation - indeed, OTEPs should be about **behaviour**, not implementation! - it may be useful to provide at least one suggestion as to how the proposal *could* be implemented. This helps reassure reviewers that implementation is at least possible, and often helps them inspire them to think more deeply about trade-offs, alternatives, etc.
24+
25+
## Trade-offs and mitigations
26+
27+
What are some (known!) drawbacks? What are some ways that they might be mitigated?
28+
29+
Note that mitigations do not need to be complete *solutions*, and that they do not need to be accomplished directly through your proposal. A suggested mitigation may even warrant its own OTEP!
30+
31+
## Prior art and alternatives
32+
33+
What are some prior and/or alternative approaches? For instance, is there a corresponding feature in OpenTracing or OpenCensus? What are some ideas that you have rejected?
34+
35+
## Open questions
36+
37+
What are some questions that you know aren't resolved yet by the OTEP? These may be questions that could be answered through further discussion, implementation experiments, or anything else that the future may bring.
38+
39+
## Future possibilities
40+
41+
What are some future changes that this proposal would enable?

oteps/README.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# OpenTelemetry Enhancement Proposal (OTEP)
2+
3+
## Evolving OpenTelemetry at the speed of Markdown
4+
5+
OpenTelemetry uses an "OTEP" (similar to a RFC) process for proposing changes to the OpenTelemetry Specification.
6+
7+
### Table of Contents
8+
9+
- [OpenTelemetry Enhancement Proposal (OTEP)](#opentelemetry-enhancement-proposal-otep)
10+
- [Evolving OpenTelemetry at the speed of Markdown](#evolving-opentelemetry-at-the-speed-of-markdown)
11+
- [Table of Contents](#table-of-contents)
12+
- [What changes require an OTEP](#what-changes-require-an-otep)
13+
- [Extrapolating cross-cutting changes](#extrapolating-cross-cutting-changes)
14+
- [OTEP scope](#otep-scope)
15+
- [Writing an OTEP](#writing-an-otep)
16+
- [Submitting the OTEP](#submitting-the-otep)
17+
- [Integrating the OTEP into the Spec](#integrating-the-otep-into-the-spec)
18+
- [Implementing the OTEP](#implementing-the-otep)
19+
- [Changes to the OTEP process](#changes-to-the-otep-process)
20+
- [Background on the OpenTelemetry OTEP process](#background-on-the-opentelemetry-otep-process)
21+
22+
### What changes require an OTEP
23+
24+
The OpenTelemetry OTEP process is intended for changes that are **cross-cutting** - that is, applicable across *languages* and *implementations* - and either **introduce new behaviour**, **change desired behaviour**, or otherwise **modify requirements**.
25+
26+
In practice, this means that OTEPs should be used for such changes as:
27+
28+
- New tracer configuration options
29+
- Additions to span data
30+
- New metric types
31+
- Modifications to extensibility requirements
32+
33+
On the other hand, they do not need to be used for such changes as:
34+
35+
- Bug fixes
36+
- Rephrasing, grammatical fixes, typos, etc.
37+
- Refactoring
38+
- Things that affect only a single language or implementation
39+
40+
**Note:** The above lists are intended only as examples and are not meant to be exhaustive. If you don't know whether a change requires an OTEP, please feel free to ask!
41+
42+
#### Extrapolating cross-cutting changes
43+
44+
Sometimes, a change that is only immediately relevant within a single language or implementation may be indicative of a problem upstream in the specification. We encourage you to add an OTEP if and when you notice such cases.
45+
46+
### OTEP scope
47+
48+
While OTEPs are intended for "significant" changes, we recommend trying to keep each OTEP's scope as small as makes sense. A general rule of thumb is that if the core functionality proposed could still provide value without a particular piece, then that piece should be removed from the proposal and used instead as an *example* (and, ideally, given its own OTEP!).
49+
50+
For example, an OTEP proposing configurable sampling *and* various samplers should instead be split into one OTEP proposing configurable sampling as well as an OTEP per sampler.
51+
52+
### Writing an OTEP
53+
54+
- First, [fork](https://help.github.com/en/articles/fork-a-repo) this repo.
55+
- Copy [`0000-template.md`](./0000-template.md) to `0000-my-OTEP.md`, where `my-OTEP` is a title relevant to your proposal, and `0000` is the OTEP ID.
56+
- Fill in the template. Put care into the details: It is important to present convincing motivation, demonstrate an understanding of the design's impact, and honestly assess the drawbacks and potential alternatives.
57+
58+
### Submitting the OTEP
59+
60+
- An OTEP is `proposed` by posting it as a PR.
61+
- An OTEP is `approved` when four reviewers github-approve the PR. The OTEP is then merged.
62+
- If an OTEP is `rejected` or `withdrawn`, the PR is closed. Note that these OTEPs submissions are still recorded, as GitHub retains both the discussion and the proposal, even if the branch is later deleted.
63+
- If an OTEP discussion becomes long, and the OTEP then goes through a major revision, the next version of the OTEP can be posted as a new PR, which references the old PR. The old PR is then closed. This makes OTEP review easier to follow and participate in.
64+
65+
### Integrating the OTEP into the Spec
66+
67+
- Once an OTEP is `approved`, an issue is created in this repo to integrate the OTEP into the actual spec.
68+
- When reviewing the spec PR for the OTEP, focus on whether the spec is written clearly, and reflects the changes approved in the OTEP. Please abstain from relitigating the approved OTEP changes at this stage.
69+
- An OTEP is `integrated` when four reviewers github-approve the spec PR. The PR is then merged, and the spec is versioned.
70+
71+
### Implementing the OTEP
72+
73+
- Once an OTEP is `integrated` into the spec, an issue is created in the backlog of every relevant OpenTelemetry implementation.
74+
- PRs are made until the all the requested changes are implemented.
75+
- The status of the OpenTelemetry implementation is updated to reflect that it is implementing a new version of the spec.
76+
77+
## Changes to the OTEP process
78+
79+
The hope and expectation is that the OTEP process will **evolve** with the OpenTelemetry. The process is by no means fixed.
80+
81+
Have suggestions? Concerns? Questions? **Please** raise an issue or raise the matter on our [community](https://github.com/open-telemetry/community) chat.
82+
83+
## Background on the OpenTelemetry OTEP process
84+
85+
Our OTEP process borrows from the [Rust RFC](https://github.com/rust-lang/rfcs) and [Kubernetes Enhancement Proposal](https://github.com/kubernetes/enhancements) processes, the former also being [very influential](https://github.com/kubernetes/enhancements/tree/master/keps/sig-architecture/0000-kep-process#prior-art) on the latter; as well as the [OpenTracing OTEP](https://github.com/opentracing/specification/tree/master/rfc_process.md) process. Massive kudos and thanks to the respective authors and communities for providing excellent prior art 💖
86+
87+
[slack-image]: https://img.shields.io/badge/Slack-4A154B?style=for-the-badge&logo=slack&logoColor=white
88+
[slack-url]: https://cloud-native.slack.com/archives/C01N7PP1THC

0 commit comments

Comments
 (0)