This repository has been archived by the owner on May 23, 2023. It is now read-only.
Versioning process for the OpenTracing specification #106
Merged
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
03251f4
Versioning Process for the OpenTracing Specification
tedsuo 4131c9a
fix typos
tedsuo ce93567
typo
tedsuo 4201ef1
typo
tedsuo 2372393
removed "updated" field from template
tedsuo c4de769
remove language around dates
tedsuo dff3ea4
merge
tedsuo 8e449db
More details
tedsuo c60a2f9
Major -> Supported
tedsuo File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
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,87 @@ | ||
# Versioning Process for the OpenTracing Specification | ||
The OpenTracing specification consists of a cross-language, abstract interface, along with an attendant set of language-specific interfaces. Every interface is versioned, with each language interface supporting a version of the abstract interface. | ||
|
||
In order effect changes to the OpenTracing specification, all interfaces are developed together in a three step process: | ||
|
||
* **DRAFT:** An RFC is drafted to define and justify the desired changes. | ||
* **TEST:** A new version of each language interface is designed, tested, and released. | ||
* **ACCEPTED:** The abstract interface is versioned to reflect the final changes. | ||
|
||
# Proposal Components | ||
|
||
## RFC (Request for Comments) | ||
Proposals begin as a single document, written in markdown and committed to the `/rfc` directory. | ||
|
||
An RFC consists of the following: | ||
|
||
* Proposal name, status, and author. | ||
* Problem statement. | ||
* Historical background. | ||
* Abstract interface. | ||
* Use cases. | ||
* Risk Assessment. | ||
|
||
An RFC has the following qualities: | ||
|
||
* The issue is clearly defined, and within the scope of the OpenTracing charter. | ||
* The utility to the OT community is illustrated with concrete use cases. It should be clear not only what will change, but how the new interface is expected to be used. | ||
* Changes to the abstract interface are clearly defined. Language-specific interfaces will be implemented in a later phase, but the abstract interface must be clear enough that the changes could be ported to many languages without much deviation. | ||
* All expected behavior should be documented, in sufficient detail such that language-specific tests and examples can be generated from the descriptions. | ||
* Risks, backwards compatibility, and potential for inconsistency are addressed. | ||
|
||
## Tracking Issue | ||
Often, a proposal will consist of multiple artifacts, such as GitHub issues, pull requests, release candidates, etc. In order to manage these resources, a single, long-running tracking issue is assigned to each proposal. | ||
|
||
A tracking issue consists of the following: | ||
|
||
* Proposal name, status, and author. | ||
* Short summary or proposal abstract. | ||
* A link to the RFC. | ||
* Lists of open issues, PRs, and upcoming deadlines. | ||
* Links to relevant artifacts, such as release candidates. | ||
* Links to meetings and other discussion channels. | ||
|
||
## Release Candidates | ||
Each language interface implements the abstract interface contained in the RFC. | ||
|
||
A complete release candidate consists of the following: | ||
* Repository branch containing the new version. | ||
* Packages for installing the new version. | ||
* More than one tracer which binds to the new version. | ||
* Major instrumentation ported to the new version. | ||
|
||
# Proposal Lifecycle | ||
|
||
## Draft | ||
* Pull request to add the draft RFC to `/rfc`. | ||
* Tracking issue for the proposal is opened. | ||
* Debate continues via pull requests against the draft. | ||
|
||
A draft proposal is first submitted as a pull request against the specification repository. | ||
|
||
Once there is consensus that the pull request meets the minimum criteria for the beginnings of a draft, and has strong potential to be accepted, the pull request is merged. A tracking issue is created at this point to manage the proposal. The draft RFC is then refined via more pull requests. | ||
|
||
Consensus is used to determine that all of the abstract proposal work has been completed, and the investigation should move to language implementations. | ||
|
||
## Test | ||
* RFC status changed from `Draft` to `Test`. | ||
* Release Candidate per supported language is created. | ||
* API conventions are coordinated between languages. | ||
* New risks and ambiguities may lead to proposal changes. | ||
|
||
Once the draft proposal is finalized, language implementation begins. Language maintainers begin creating a release candidate on a branch of the language repository. Links to the release candidates, along with their status, are recorded in the tracking issue. Multiple tracers create a branch which is compatible with new API, along with important instrumentation libraries. These assest are then used to vet the new API, exploring edge cases and potential issues. | ||
|
||
At this stage, issues and further refinements are surfaced and debated via tested examples, as English often is too imprecise to address the finer points of API design. | ||
|
||
## Accepted | ||
* Remaining language interfaces are released. | ||
* Abstract interface is versioned and updated. | ||
* Documentation is updated. | ||
* RFC status changed from `Test` to `Accepted`. | ||
* Tracking issue for the proposal is closed. | ||
|
||
After a quorum of language interfaces have been tested and released, consensus may be reached that a proposal has been finalized. At this point, the abstract interface contained in the `specification.md` document is updated to reflect the final changes, based on the language in the RFC document and release candidates. | ||
|
||
In addition to the specification, the OpenTracing website and other major documentation efforts are updated at this time to reflect the latest version. Once all work is complete, the tracking issue is closed. | ||
|
||
|
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,20 @@ | ||
# RFC_NAME | ||
|
||
**Current State:** Draft | ||
**Author:** GITHUB_HANDLE | ||
|
||
The opening section of the RFC is used to define the problem. The motivating issue must be clearly defined, and the requested changes must within the scope of the OpenTracing charter. | ||
|
||
# Background | ||
Relevant historical context is summarized here. Since Since OpenTracing is a standardization effort, successful proposals will usually be based on existing academic research and insustry solutions. References to any prior proposals or standardization efforts should also be included. | ||
|
||
# Specification Changes | ||
Changes to the abstract interface must be clearly defined. Language-specific interfaces will be implemented in a later phase, and the abstract interface contained here must be clear enough such that the changes can be ported to many languages without much deviation. | ||
|
||
All expected behavior should be documented, in sufficient detail such that language-specific tests and examples can be generated from the descriptions. | ||
|
||
# Use Cases | ||
Concrete use cases must be provided, in order to guide testing and interface design, and assist reviewers. | ||
|
||
# Risk Assessment | ||
Risks, backwards compatibility, and potential for inconsistency are addressed. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+1