Versioning process for the OpenTracing specification #106

tedsuo · 2018-02-28T18:58:54Z

RFC Proposal

https://github.com/opentracing/specification/blob/tedsuo/rfc-process/rfc_process.md
Defines a more formal versioning process for the OpenTracing specification.

RFC Template

https://github.com/opentracing/specification/blob/tedsuo/rfc-process/rfc_template.md
To be used for starting proposals.

Example RFC

#107 Trace-Parent Accessors
A real change request, done in the format defined within this pull request.

Inspiration and prior art

Couchbase: https://github.com/couchbaselabs/sdk-rfcs/
IETF
W3C

yurishkuro

lgtm

yurishkuro · 2018-03-01T00:21:02Z

rfc_process.md

+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 langauage interface is designed, tested, and released.


typo: langauage

cwe1ss · 2018-03-01T14:56:35Z

rfc_process.md

+* Historical background.
+* Abstract interface.
+* Use cases.
+* Risk Assesment.


should be "Assessment", right?

cwe1ss · 2018-03-01T14:57:32Z

rfc_process.md

+
+* 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.


missing space after the comma.

cwe1ss · 2018-03-01T14:59:00Z

rfc_process.md

+* Repository branch containing the new version.
+* Packages for installing the new version.
+* Tracers which bind to the new version.
+* Major instrmentation ported to the new version.


typo: instrmentation

cwe1ss · 2018-03-01T15:04:12Z

rfc_process.md

+A complete release candidate consists of the following:
+* Repository branch containing the new version.
+* Packages for installing the new version.
+* Tracers which bind to the new version.


How should we define/choose which tracer should try to implement a feature? Do we just rely on the fact that people here are working on tracers anyway and will implement features in "their" tracers? Also, tracers are more or less separate projects with separate release cyclesoutside of our direct control (but tied to us of course). Maybe it would be easier if every language had the "basic tracer" which could be used to show the usage of the feature?

In general, I believe we should use "rough consensus" for making these decisions. No one can use an API without at least one tracer and one complete set of instrumentation (framework plus RPC library). So an API can't really be examined without these. Ideally, a new release candidate is not made official without at least support from some tracers and instrumentation, or it is useless to people. As to which ones and how many, that should be a case by case basis. For example, which tracers support C# might be different from those which support C++.

We definitely need to revisit the Basic Tracers and make them more useful, but I don't think they are a substitute.

cwe1ss · 2018-03-01T15:09:02Z

rfc_process.md

+* 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.
+


This no longer explains the previously mentioned point Tracers which bind to the new version.. See my previous comment for questions regarding it.

Ok, sounds like more detail is needed to describe the Test stage.

cwe1ss · 2018-03-01T15:10:35Z

rfc_process.md

+* 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 docment and release candidates.


Isn't this already done via the "Accepted" stage that says that the "Abstract interface is versioned and updated"?

Not sure what distinction you are making. This is a description of the Accepted stage.

my bad - I thought this was a new paragraph.

cwe1ss · 2018-03-01T15:10:52Z

rfc_process.md

+
+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 docment and release candidates.
+
+In addition to the specification, the OpenTracing website and other major docmentation efforts are updated at this time to reflect the latest version. Once all work is complete, the tracking issue is closed.


typo: docmentation

cwe1ss · 2018-03-01T15:14:22Z

rfc_template.md

@@ -0,0 +1,18 @@
+# 0001: RFC_NAME


Do we really need numbered RFCs? They will have separate lifetimes and later RFCs might be released earlier etc. Also, it might be hard to know what the next free number is. (One might have to look through open and closed issues etc.)

As a different solution, e.g. in the "C# language" repository, they just use names for their proposals.

Should be clear what the next free number is when you commit (may be different than when you started, of course). Hopefully we are not accepting proposals so fast that there is some kind of race condition. :)

That said, I am not wedded to numbered RFCs. For me, it's simply a matter of how we would like the files organized, so they aren't just in one big arbitrary pile. Possibly directories like C# uses would also be a good approach.

cwe1ss · 2018-03-01T15:15:44Z

rfc_template.md

@@ -0,0 +1,18 @@
+# 0001: RFC_NAME
+
+**Updated:** January 01, 2018  


Since files are committed markdown files with a git history, it might not be necessary to use a "Updated" column. Maybe it's enough to keep dates for state changes?

Yeah, could be fine! I'm down to remove this.

cwe1ss · 2018-03-01T15:17:22Z

rfc_template.md

+# Use Cases
+Concrete use cases must be provided, in order to guide testing and interface design, and assist reviewers.
+
+# Risk Assesment


typo: I think it should be "Assessment"

tedsuo · 2018-03-13T22:17:09Z

I'd like to merge this in on Friday, March 16th, after the Cross-Language working group meeting. If you have objections or questions, please give them this week.

jpkrohling · 2018-03-20T10:38:46Z

rfc_process.md

+
+# Proposal Components
+
+## RFC (Request for Change)


Usually, "RFC" is a "request for comments", not change. Did you really mean "change"?

jpkrohling · 2018-03-20T10:45:11Z

rfc_process.md

+* 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.


jpkrohling · 2018-03-20T10:47:32Z

rfc_process.md

+
+## Test
+* RFC status changed from `Draft` to `Test`.
+* Release Candidate per major language is created.


Do we have a list of "major languages" defined somewhere?

good point, "supported language" is a better term.

* bold text * RFC means Request for Comments * Fill in details about the Testing stage.

tedsuo · 2018-03-20T21:28:21Z

@cwe1ss @jpkrohling thank you for your feedback. I've made changes based on your suggestions, and I'm going to merge. Feel free to make additional PRs if you find further changes.

Versioning Process for the OpenTracing Specification

03251f4

tedsuo requested review from yurishkuro and pavolloffay February 28, 2018 21:31

yurishkuro approved these changes Mar 1, 2018

View reviewed changes

yurishkuro reviewed Mar 1, 2018

View reviewed changes

cwe1ss reviewed Mar 1, 2018

View reviewed changes

tedsuo added 6 commits March 1, 2018 13:51

fix typos

4131c9a

typo

ce93567

typo

4201ef1

removed "updated" field from template

2372393

remove language around dates

c4de769

merge

dff3ea4

cwe1ss approved these changes Mar 14, 2018

View reviewed changes

jpkrohling approved these changes Mar 20, 2018

View reviewed changes

tedsuo added 2 commits March 20, 2018 14:23

More details

8e449db

* bold text * RFC means Request for Comments * Fill in details about the Testing stage.

Major -> Supported

c60a2f9

tedsuo merged commit 0805d3d into master Mar 20, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Versioning process for the OpenTracing specification #106

Versioning process for the OpenTracing specification #106

tedsuo commented Feb 28, 2018 •

edited

yurishkuro left a comment

yurishkuro Mar 1, 2018

cwe1ss Mar 1, 2018

cwe1ss Mar 1, 2018

cwe1ss Mar 1, 2018

cwe1ss Mar 1, 2018

tedsuo Mar 1, 2018

cwe1ss Mar 1, 2018

tedsuo Mar 1, 2018

cwe1ss Mar 1, 2018

tedsuo Mar 1, 2018

cwe1ss Mar 2, 2018

cwe1ss Mar 1, 2018

cwe1ss Mar 1, 2018

tedsuo Mar 1, 2018

cwe1ss Mar 1, 2018

tedsuo Mar 1, 2018

cwe1ss Mar 1, 2018

tedsuo commented Mar 13, 2018

jpkrohling Mar 20, 2018

jpkrohling Mar 20, 2018

jpkrohling Mar 20, 2018

tedsuo Mar 20, 2018

tedsuo commented Mar 20, 2018

		* 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.


		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 docment and release candidates.

		In addition to the specification, the OpenTracing website and other major docmentation efforts are updated at this time to reflect the latest version. Once all work is complete, the tracking issue is closed.

		@@ -0,0 +1,18 @@
		# 0001: RFC_NAME

		Updated: January 01, 2018

Versioning process for the OpenTracing specification #106

Versioning process for the OpenTracing specification #106

Conversation

tedsuo commented Feb 28, 2018 • edited

RFC Proposal

RFC Template

Example RFC

Inspiration and prior art

yurishkuro left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tedsuo commented Mar 13, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tedsuo commented Mar 20, 2018

tedsuo commented Feb 28, 2018 •

edited