|
| 1 | +--- |
| 2 | +title: Shared Signals Versioning Proposal - draft 01 |
| 3 | +abbrev: SharedSignals-Versioning |
| 4 | +docname: openid-sharedsignals-versioning-1_0 |
| 5 | +date: 2023-08-14 |
| 6 | +author: |
| 7 | + - |
| 8 | + ins: A. Tulshibagwale |
| 9 | + name: Atul Tulshibagwale |
| 10 | + org: SGNL |
| 11 | + email: atul@sgnl.ai |
| 12 | +ipr: none |
| 13 | +cat: std |
| 14 | +wg: Shared Signals |
| 15 | + |
| 16 | +--- abstract |
| 17 | +This versioning proposal defines a numbering scheme for versions of all output of the OpenID Shared Signals Working Group |
| 18 | + |
| 19 | +--- middle |
| 20 | + |
| 21 | +# Background |
| 22 | +The OpenID standardization process has three steps: |
| 23 | + |
| 24 | +1. A draft spec is worked on in the working group |
| 25 | +2. A draft spec is accepted by the OpenID Foundation as an “Implementer’s Draft” |
| 26 | +3. An Implementer’s Draft is accepted by the OpenID Foundation as a Final Specification. |
| 27 | + |
| 28 | + |
| 29 | +For the purposes of this document, the latest accepted Implementer’s Draft is called the “Latest Spec”. |
| 30 | + |
| 31 | +## Protocol Versions |
| 32 | +In the case of the Shared Signals Framework (SSF), a newer draft may change something about the protocol, i.e. the API, event formats, metadata formats, etc. These changes can be categorized as follows: |
| 33 | + |
| 34 | +1. **No Change**: The new version makes no changes to the API, event formats or metadata formats or other properties of the protocol it describes that differs from the Latest Spec. |
| 35 | +2. **Backward Compatible Change**: The new version adds optional properties or methods to the Latest Spec, but an implementation of the Latest Spec that does not implement the new features can continue to operate without seeing any difference in the behavior from the peer that has implemented some or all of the new optional properties. |
| 36 | +3. **Breaking Change**: The new version makes changes to the Latest Spec. Implementations need to be updated in order to be able to work with any implementation of this new version. |
| 37 | + |
| 38 | +**Note** that the change is always compared against the Latest Spec, and not against previous working group drafts. |
| 39 | +Versioning Proposal |
| 40 | +Version numbers are represented as decimal numbers, including at least one numeral after the decimal point even if it is the value “0”. |
| 41 | + |
| 42 | +The Latest Spec version, although not specified in the metadata or anywhere else in the Latest Spec, is assumed to be “0.1”. |
| 43 | + |
| 44 | +For all versions starting now (i.e. as of Aug 14, 2023), we will do the following: |
| 45 | + |
| 46 | +1. Include a “version” field in the Transmitter Configuration Metadata |
| 47 | +2. Keep the version number the same if it represents No Change |
| 48 | +3. Increment the version number to the right of the decimal point if the new version represents a Backward Compatible Change |
| 49 | +4. Increment the version number to the left of the decimal point and set the version number to the right of the decimal point to “0”, if the new version represents a Breaking change |
| 50 | + |
| 51 | +**Note** that as a draft progresses through the standardization process, the version numbers do not change until the change is accepted as an Implementer’s Draft (therefore becoming a new Latest Spec). The version number does not change when the Latest Spec is accepted as a Final Specification. GitHub commits that are used to create a Latest Spec will be tagged to the version number of the corresponding document. |
| 52 | + |
| 53 | +**Note** that it is possible for a Transmitter to support multiple versions by providing different endpoints that communicate using the version specified in the metadata of that collection of endpoints. |
| 54 | + |
| 55 | +# Example |
| 56 | +The current Latest Spec version is “0.1”. The draft currently being worked on will be called “1.0”. This number will remain unchanged if the current draft or some successor of it (regardless of whether the drafts have more Breaking Changes or Backward Compatible Changes) will remain “1.0” until it becomes an Implementer’s Draft. |
| 57 | + |
| 58 | +Suppose a successive working group draft makes a Backward Compatible Change after the version of the Latest Spec is “1.0”, then the new working group draft will have the version number “1.1”. Even if successive versions of the working group draft make more Backward Compatible Changes, the version number will remain “1.1” until some working group draft becomes accepted as an Implementer’s Draft. |
| 59 | + |
| 60 | +Suppose a successive working group draft after the Latest Spec version is “1.1” makes a Breaking Change, the new working group draft will be called “2.0”. Until this draft becomes the Latest Spec, regardless of how many more Breaking Changes occur in successive working group drafts, the version remains “2.0”. |
| 61 | + |
| 62 | +Suppose the next Final Specification that is accepted is “1.1”, it does not change anything about the “2.0” number of the working group draft. |
| 63 | + |
| 64 | +--- back |
| 65 | + |
| 66 | +# Acknowledgements |
| 67 | + |
| 68 | +The author wishes to thank all members of the OpenID Foundation Shared Signals Working Group who contributed to the development of this specification. |
| 69 | + |
| 70 | +# Notices |
| 71 | + |
| 72 | +Copyright (c) 2023 The OpenID Foundation. |
| 73 | + |
| 74 | +The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF. |
| 75 | + |
| 76 | +The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification. |
0 commit comments