idnits 2.17.1 draft-claise-semver-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 140: '...he specification MUST be converted int...' RFC 2119 keyword, line 142: '... with a MAJOR version change MUST also...' RFC 2119 keyword, line 149: '... actions MUST be converted into Inte...' RFC 2119 keyword, line 150: '...ithout such impacts MAY be approved by...' RFC 2119 keyword, line 151: '...p. PATCH-level changes MAY be made by...' (2 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 20, 2017) is 2502 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 374 looks like a reference -- Missing reference section? '2' on line 376 looks like a reference -- Missing reference section? '3' on line 378 looks like a reference Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Claise 3 Internet-Draft R. Barnes 4 Intended status: Standards Track J. Clarke 5 Expires: December 22, 2017 Cisco 6 June 20, 2017 8 Semantic Versioning and Structure for IETF Specifications 9 draft-claise-semver-00 11 Abstract 13 In the Internet engineering ecosystem, there is increasingly a need 14 for specifications that evolve over time, and are encoded directly in 15 structured formats (e.g., YANG models). Internet-Drafts are a poor 16 fit for working groups that want to produce structured 17 specifications, and publishing versions of an evolving specification 18 as RFC makes it difficult to track the specification over time. This 19 document outlines recommendations for how working groups can provide 20 semantic versioning for, and work directly on, structured documents 21 while still fitting within established IETF processes. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on December 22, 2017. 40 Copyright Notice 42 Copyright (c) 2017 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. Managing Semantic Versions . . . . . . . . . . . . . . . . . 3 59 2.1. Versioning for Work in Progress . . . . . . . . . . . . . 4 60 3. IETF Consensus for Structured Specifications . . . . . . . . 5 61 4. Example history . . . . . . . . . . . . . . . . . . . . . . . 5 62 5. Creating Internet-Drafts from a Repository . . . . . . . . . 8 63 6.1. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 66 1. Introduction 68 The pace at which the software that drives the Internet is developed 69 and deployed today is much faster than it was early in the Internet's 70 history. In this environment, maintaining interoperability can be 71 more challenging. 73 Two of the major mechanisms that have been developed for driving 74 interoperability in a more dynamic ecosystem are semantic versioning 75 and structured specifications. Structured specifications allow much 76 of the work of implementing a specification to be automated, so that 77 developers can focus on the parts of a specification that really need 78 human involvement. Semantic versioning helps operators know what 79 versions can be deployed without breaking running systems, so that 80 they can safely deploy updated versions of a specification more 81 quickly. 83 The traditional practices of the IETF interact poorly with these 84 mechanisms. Each document presented to the IETF for last call and 85 IESG approval must be formatted as an Internet-Draft, i.e., as 86 unstructured text. All RFCs across the IETF share a single, common 87 numbering space, so that RFC numbers have no useful semantic with 88 respect to versioning. Nonetheless, there is still a need to be able 89 to capture the consensus of the IETF at critical points in the life- 90 cycle of a specification. 92 This document describes recommendations for how a working group (WG) 93 that wishes to produce structured specifications with semantic 94 version numbers can interact best with IETF processes. 96 2. Managing Semantic Versions 98 While some of this process might apply to completely new work (such 99 as a YANG module), the process in this document applies to WG adopted 100 work items or to modification of an existing IETF-approved work item 101 (typically a bis document ). 103 We start from the premise that a working group controls a version- 104 controlled repository (e.g., Git, SVN, etc.) for a structured 105 specification (not formatted as an Working Group Internet-Draft), and 106 can "tag" commits in the repository as having certain version 107 numbers. We assume that there is one repository per specification, 108 so that version tags don't need to specify which specification they 109 refer to. 111 The recommended structure for semantic versions follows the widely- 112 used three-part convention, with an additional field for use in 113 working group processes: 115 MAJOR.MINOR.PATCH 117 The fields in such a structured version have the following semantics 118 (cf. semver.org): 120 o MAJOR is incremented when the new version of the specification is 121 incompatible with previous versions. 123 o MINOR is incremented when new functionality is added in a manner 124 that is backward-compatible with previous versions. 126 o PATCH is incremented when bug fixes are made in a backward- 127 compatible manner. 129 In IETF terms, this versioning scheme provides functionality 130 analogous to several parts of the traditional IETF process. 132 o MAJOR is analogous to an "obsoletes" relation between RFCs 134 o MINOR is analogous to an "updates" relation between RFCs 136 o PATCH is analogous to use of the RFC errata process 138 The more major a change to the specification, the more consensus is 139 required. When the WG wants to make a MAJOR change to a structured 140 specification, the specification MUST be converted into Internet- 141 Draft format and run through the typical IETF consensus process. 142 Every commit that is tagged with a MAJOR version change MUST also 143 have a tag indicating the number of the RFC describing the change. 145 For MINOR changes, WG consensus is required. The WG chairs can 146 additionally decide whether IETF consensus is required. Any change 147 to the structured specification that significantly changes the 148 security considerations for the protocol or requires additional IANA 149 actions MUST be converted into Internet-Draft format and submitted 150 for IETF consensus. Changes without such impacts MAY be approved by 151 consensus of the working group. PATCH-level changes MAY be made by 152 the editors, with the consent of the WG chairs. 154 When a working group starts up work on a new version of the 155 specification, regardless of whether it's a minor update or a 156 complete rewrite, they SHOULD create a dedicated branch of the 157 repository for the new version, where changes related to the new 158 version will be committed. The semantic version, i.e. MAJOR and 159 MINOR is assigned when this branch is merged back to the main 160 specification. Once there is consensus to update the main 161 specification to that version, the branch should be merged, and the 162 merge commit tagged with the new version number. 164 When working on modification to an existing work item (typically a 165 bis document), the process is to fork a git repo, branch, make a 166 proposal, then push the branch back over to the Working Group when/if 167 the Working Group adopts it. 169 2.1. Versioning for Work in Progress 171 It can be useful to mark certain versions of a work in progress as 172 checkpoints, e.g., for reference at a hackathon. These checkpoints 173 should follow their own version sequence, much like Internet drafts: 175 LABEL-VERSION 177 o LABEL is a string that identifies the feature branch 179 o VERSION is incremented whenever a new revision is tagged 181 These tags are analogous to Internet-Draft names. Much like an 182 Internet-Draft name, the choice of LABEL values is up to the editors 183 and WG chairs. In cases what they expect the completed work to 184 result in a given version, then they might use that as a label value. 185 For example, if the WG has agreed to embark on a major revision to 186 the protocol, then they might use the label "v2.0.0-beta", so that 187 the working revisions would be "v2.0.0-beta-0", "v2.0.0-beta-1", etc. 189 It's important to note that not every commit needs a version. Much 190 like working groups using Github to manage Internet-Drafts today only 191 periodically submit them to the IETF, a WG can do work in a 192 repository and only tag versions when they are useful to the WG. 194 Beta versions should be tagged at key points in the development 195 process: 197 o Before an IETF meeting or WG interim meeting 199 o Before a hackathon or interop event 201 o Before a working group or IETF last call 203 Work on a new version SHOULD be conducted on a dedicated branch. 204 Once there is consensus to update the main specification to that 205 version, the branch should be merged, and the merge commit tagged 206 with the new version number. 208 3. IETF Consensus for Structured Specifications 210 While working groups may use any format for specifications under 211 development, the Internet Standards process requires that a document 212 proposed as an RFC must be submitted in the RFC format, i.e., as 213 unstructured text. Proposed RFCs are also required to contain 214 explanatory text not typically contained in structured 215 specifications, most notably Security Considerations and IANA 216 Considerations. Thus, a working group that is focused mainly on a 217 structured specification will have to convert the structured 218 specification to the RFC format and add the additional explanatory 219 text. 221 In order to keep the repository as the primary home for the 222 specification, the working group should keep any required explanatory 223 text in the repository alongside the structured specification, and 224 use automated tools to generate an RFC-formatted document from the 225 artifacts in the repository. As the outputs are reviewed in the IETF 226 last call and IESG processes, the editors should reflect their 227 responses in the repository, generating updated versions of the RFC- 228 formatted document as necessary. 230 Whenever an Internet-Draft is generated from the repository, the 231 corresponding commit in the repository should be tagged with the full 232 name and version of the Internet-Draft. Additionally, a reference to 233 the repository (e.g., a URL) should exist in the text of the 234 resulting Internet-Draft. These steps enable the evolution of the 235 draft to easily be tied back to the evolution of the repository. 237 4. Example history 239 The below sequence of commits and tags shows the progress of a 240 structured specification through several stages of its life-cycle. 242 (Time flows up from the bottom, as is common in version control 243 logs.) 245 An initial version of a protocol is proposed for a Birds of a Feather 246 (BoF) and a WG is formed. The WG develops version 1.0.0 of the 247 specification. Along the way, they tag betas when they need an easy 248 way to refer to a version, e.g., before working group last call 249 (WGLC). 251 Once the WG has reached consensus, an Internet-Draft is created from 252 the repository (draft-ietf-wg-proto-00) and submitted for the IETF 253 consensus process, resulting in an RFC (RFC XXX1) that describes the 254 first version of the protocol. In this example, there is never a 255 need to publish an individual (author-named) internet-draft, because 256 the WG worked directly on the structured specification and obtained 257 consensus on it. 259 Comments from the IETF last call (LC) and the IESG are incorporated 260 in the repository, and new versions of the Internet-Draft are 261 generated for IESG review and submission to the RFC editor. 263 ... 264 | 265 * e3091df (tag:v1.0.0, tag:draft-ietf-wg-proto-02, tag:RFCXXX1) 266 | Responses to IESG comments 267 | 268 * 7494725 (tag:draft-ietf-wg-proto-01) Responses to IETF LC comments 269 | 270 * 8e2be54 (tag:proto-2, tag:draft-ietf-wg-proto-00) 271 | Responses to WGLC comments 272 | 273 * 9703a60 (tag:proto-1) Responses to comments at IETF meeting 274 | 275 * 2b83977 Responses to J. Smith comments 276 | 277 * 8b75e1e (tag:proto-0) Responses to BoF comments 278 | 279 * 1991498 Initial submission 281 The WG adds two features to the specification. The first feature is 282 major enough that the chairs decide it needs IETF consensus, 283 resulting in a second Internet-Draft going through the IETF consensus 284 process (draft-ietf-wg-proto-feature-00) to become an RFC (RFC XXX2). 285 The second feature is minor enough that it can be approved by WG 286 consensus. 288 ... 289 | 290 * a5f3214 (tag:v1.2.0) Merge branch 'v1.2' 291 |\ 292 | * 8fb9cb6 Responses to WGLC comments on feature Y 293 | | 294 | * 39322e9 (tag:featureY-1) Responses to WG comments; ready for WGLC 295 | | 296 | * 39322e9 Add feature Y 297 |/ 298 * d1d201d (tag:v1.1.1) Fix validation errors 299 | 300 * 6571483 (tag:v1.1.0, tag:draft-ietf-wg-proto-feature-04, 301 | tag:RFCXXX2) Merge branch 'v1.1' 302 |\ 303 | * abc3f5e (tag:draft-ietf-wg-proto-feature-03) Resolution of DISCUSSes 304 | | from Security AD 305 | | 306 | * 3ab54f3 (tag:draft-ietf-wg-proto-feature-02) Resolution of DISCUSSes 307 | | from Internet and Transport ADs 308 | | 309 | * cabb1f6 (tag:draft-ietf-wg-proto-feature-01) Responses to WGLC 310 | | and IETF LC comments on feature X 311 | | 312 | * fbfaa6b (tag:featureX-0, tag:draft-ietf-wg-proto-feature-00) 313 | | Responses to comments on feature X 314 | | 315 | * 0630638 Add feature X 316 |/ 317 * e3091df (tag:v1.0.0, tag:draft-ietf-wg-proto-02, tag:RFCXXX1) 318 | Responses to IESG comments 319 | 320 ... 322 The WG develops a major revision of the protocol, resulting in a 323 third Internet-Draft (draft-ietf-wg-protobis-00) going through the 324 IETF consensus process, resulting in RFC XXX3. 326 ... 327 | 328 * a9d7d29 (tag:v2.0.0, tag:draft-ietf-wg-protobis-01 tag:RFCXXX3) 329 | Merge branch 'v2' 330 |\ 331 | * df5d437 (tag:draft-ietf-wg-protobis-00) Responses to 332 | | WGLC and IETF LC comments 333 | | 334 | * 986ebb6 (tag:v2.0.0-beta-1) Checkpoint for hackathon 335 | | 336 | * d86986e (tag:v2.0.0-beta-0) Some more v2 features 337 | | 338 | * ca02154 Restructure for v2 339 |/ 340 * a5f3214 (tag:v1.2.0) Merge branch 'v1.2' 341 | 342 ... 344 This example history is greatly simplified. In a real WG, there will 345 be far more commits without versions, as the WG incorporates 346 proposals, edits explanatory text, etc. But this example highlights 347 the key moments in the life-cycle of a specification. 349 5. Creating Internet-Drafts from a Repository 351 As noted above, WGs should have one repository per specification. 352 Over the lifetime of the specification, it will be necessary for 353 automated tools to build Internet-Drafts from this repository. A 354 standardized repository layout can help automate this process. 356 The root level of the repository should have a file named "index.xml" 357 or "index.md", depending on whether XML [1] or Markdown [2] is being 358 used. This file should itself be a valid source for an Internet- 359 Draft, including information about the title to be used, authors' / 360 editors' names, security considerations, etc. It will act as a 361 template into which the structured specification will be included 362 when an Internet-Draft is created. 364 The template file should include files that comprise the structured 365 specification as figures at appropriate points in the draft. The 366 Markdown syntax provided by "mmark" provides a syntax for including 367 code fragments [3] from external files, including the ability to 368 selectively include parts of a file. 370 6. References 372 6.1. URIs 374 [1] https://tools.ietf.org/html/rfc7991 376 [2] https://github.com/miekg/mmark/wiki/Syntax 378 [3] https://github.com/miekg/mmark/wiki/Syntax#including-code- 379 fragments 381 Authors' Addresses 383 Benoit Claise 384 Cisco 386 Email: bclaise@cisco.com 388 Richard Barnes 389 Cisco 391 Email: rlb@ipv.sx 393 Joe Clarke 394 Cisco 396 Email: jclarke@cisco.com