idnits 2.17.1 draft-claise-semver-01.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 a Security Considerations section. ** 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 141: '...he specification MUST be converted int...' RFC 2119 keyword, line 143: '... with a MAJOR version change MUST also...' RFC 2119 keyword, line 148: '... for the WG MAY approve the issuance...' RFC 2119 keyword, line 151: '...quires additional IANA actions MUST be...' RFC 2119 keyword, line 154: '... such impacts MAY be approved by con...' (3 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 18, 2017) is 2445 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 377 looks like a reference -- Missing reference section? '2' on line 379 looks like a reference -- Missing reference section? '3' on line 381 looks like a reference Summary: 4 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: January 19, 2018 Cisco 6 July 18, 2017 8 Semantic Versioning and Structure for IETF Specifications 9 draft-claise-semver-01 11 Abstract 13 In the Internet engineering ecosystem, there is increasingly a need 14 for specifications that evolve over time, and which are encoded 15 directly in structured formats (e.g., YANG models). Internet-Drafts 16 are a poor 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 consistent, meaningful versions for specifications over time and work 21 directly on structured documents while still fitting within 22 established IETF processes. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on January 19, 2018. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Managing Semantic Versions . . . . . . . . . . . . . . . . . 3 60 2.1. Versioning for Work in Progress . . . . . . . . . . . . . 4 61 3. IETF Consensus for Structured Specifications . . . . . . . . 5 62 4. Example history . . . . . . . . . . . . . . . . . . . . . . . 6 63 5. Creating Internet-Drafts from a Repository . . . . . . . . . 8 64 6.1. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 67 1. Introduction 69 The pace at which the software that drives the Internet is developed 70 and deployed today is much faster than it was early in the Internet's 71 history. In this environment, maintaining interoperability can be 72 more challenging. 74 Two of the major mechanisms that have been developed for driving 75 interoperability in a more dynamic ecosystem are structured 76 specifications and semantic versioning. Structured specifications 77 allow much of the work of implementing a specification to be 78 automated, so that developers can focus on the parts of a 79 specification that really need human involvement. Semantic 80 versioning helps operators know what versions can be deployed without 81 breaking running systems, so that they can safely deploy updated 82 versions of a specification more quickly. 84 The traditional practices of the IETF interact poorly with these 85 mechanisms. Each document presented to the IETF for last call and 86 IESG approval must be formatted as an Internet-Draft, i.e., as 87 unstructured text. All RFCs across the IETF share a single, common 88 numbering space, so that RFC numbers have no useful semantic with 89 respect to versioning. Nonetheless, there is still a need to be able 90 to capture the consensus of the IETF at critical points in the life- 91 cycle of a specification. 93 This document describes recommendations for how a working group (WG) 94 that wishes to produce structured specifications with semantic 95 version numbers can interact best with IETF processes. 97 2. Managing Semantic Versions 99 While some of this process might apply to completely new work (such 100 as a YANG module), the process in this document applies to WG adopted 101 work items or to modification of an existing IETF-approved work item 102 (typically a bis document). 104 We start from the premise that a working group controls a version- 105 controlled repository (e.g., Git, SVN, etc.) for a structured 106 specification (not formatted as an Working Group Internet-Draft), and 107 can "tag" commits in the repository as having certain version 108 numbers. We assume that there is one repository per specification, 109 so that version tags don't need to state the specification to which 110 they refer. 112 The recommended structure for semantic versions follows the widely- 113 used three-part convention, with an additional field for use in 114 working group processes: 116 MAJOR.MINOR.PATCH 118 The fields in such a structured version have the following semantics 119 (cf. semver.org): 121 o MAJOR is incremented when the new version of the specification is 122 incompatible with previous versions. 124 o MINOR is incremented when new functionality is added in a manner 125 that is backward-compatible with previous versions. 127 o PATCH is incremented when bug fixes are made in a backward- 128 compatible manner. 130 In IETF terms, this versioning scheme provides functionality 131 analogous to several parts of the traditional IETF process. 133 o MAJOR is analogous to an "obsoletes" relation between RFCs 135 o MINOR is analogous to an "updates" relation between RFCs 137 o PATCH is analogous to use of the RFC errata process 139 The more major a change to the specification, the more consensus is 140 required. When the WG wants to make a MAJOR change to a structured 141 specification, the specification MUST be converted into Internet- 142 Draft format and run through the typical IETF consensus process. 143 Every commit that is tagged with a MAJOR version change MUST also 144 have a tag of the form "RFC-XXXX" indicating the number of the RFC 145 describing the change. 147 MINOR changes follow the same rules, except that the Area Director 148 for the WG MAY approve the issuance of a minor version with only WG 149 consensus, not full IETF consensus. Any change to the structured 150 specification that significantly changes the security considerations 151 for the protocol or requires additional IANA actions MUST be 152 converted into Internet-Draft format and submitted for IETF 153 consensus. With the approval of the AD for the WG, changes without 154 such impacts MAY be approved by consensus of the working group. 156 PATCH-level changes MAY be made by the editors, with the consent of 157 the WG chairs. 159 When a working group starts up work on a new version of the 160 specification, regardless of whether it's a minor update or a 161 complete rewrite, they SHOULD create a dedicated branch of the 162 repository for the new version, where changes related to the new 163 version will be committed. The semantic version, i.e. MAJOR and 164 MINOR is assigned when this branch is merged back to the main 165 specification. Once there is consensus to update the main 166 specification to that version, the branch should be merged, and the 167 merge commit tagged with the new version number. 169 When working on modification to an existing work item (typically a 170 bis document), the process is to fork a git repo, branch, make a 171 proposal, then push the branch back over to the Working Group when/if 172 the Working Group adopts it. 174 2.1. Versioning for Work in Progress 176 It can be useful to mark certain versions of a work in progress as 177 checkpoints, e.g., for reference at a hackathon. These checkpoints 178 should follow their own version sequence, much like Internet drafts: 180 LABEL-VERSION 182 o LABEL is a string that identifies the feature branch 184 o VERSION is incremented whenever a new revision is tagged 186 These tags are analogous to Internet-Draft names. Much like an 187 Internet-Draft name, the choice of LABEL values is up to the editors 188 and WG chairs. For cases expected to result in a given version, they 189 may choose to use that as a label value. For example, if the WG has 190 agreed to embark on a major revision to the protocol, then they might 191 use the label "v2.0.0-beta", so that the working revisions would be 192 "v2.0.0-beta-0", "v2.0.0-beta-1", etc. 194 It's important to note that not every commit needs a version. Much 195 like working groups using Github to manage Internet-Drafts today only 196 periodically submit them to the IETF, a WG can do work in a 197 repository and only tag versions when they are useful to the WG. 198 Beta versions should be tagged at key points in the development 199 process: 201 o Before an IETF meeting or WG interim meeting 203 o Before a hackathon or interop event 205 o Before a working group or IETF last call 207 Work on a new version SHOULD be conducted on a dedicated branch. 208 Once there is consensus to update the main specification to that 209 version, the branch should be merged, and the merge commit tagged 210 with the new version number. 212 3. IETF Consensus for Structured Specifications 214 While working groups may use any format for specifications under 215 development, the Internet Standards process requires that a document 216 proposed as an RFC must be submitted in the RFC format, i.e., as 217 unstructured text. Proposed RFCs are also required to contain 218 explanatory text not typically contained in structured 219 specifications, most notably Security Considerations and IANA 220 Considerations. Thus, a working group that is focused mainly on a 221 structured specification will have to convert the structured 222 specification to the RFC format and add the additional explanatory 223 text. 225 In order to keep the repository as the primary home for the 226 specification, the working group should keep any required explanatory 227 text in the repository alongside the structured specification, and 228 use automated tools to generate an RFC-formatted document from the 229 artifacts in the repository. As the outputs are reviewed in the IETF 230 last call and IESG processes, the editors should reflect their 231 responses in the repository, generating updated versions of the RFC- 232 formatted document as necessary. 234 Whenever an Internet-Draft is generated from the repository, the 235 corresponding commit in the repository should be tagged with the full 236 name and version of the Internet-Draft. Additionally, a reference to 237 the repository (e.g., a URL) should exist in the text of the 238 resulting Internet-Draft. These steps enable the evolution of the 239 draft to easily be tied back to the evolution of the repository. 241 4. Example history 243 The below sequence of commits and tags shows the progress of a 244 structured specification through several stages of its life-cycle. 245 (Time flows up from the bottom, as is common in version control logs; 246 most recent is on top.) 248 An initial version of a protocol is proposed for a Birds of a Feather 249 (BoF) and a WG is formed. The WG develops version 1.0.0 of the 250 specification. Along the way, they tag betas when they need an easy 251 way to refer to a version, e.g., before working group last call 252 (WGLC). 254 Once the WG has reached consensus, an Internet-Draft is created from 255 the repository (draft-ietf-wg-proto-00) and submitted for the IETF 256 consensus process, resulting in an RFC (RFC XXX1) that describes the 257 first version of the protocol. In this example, there is never a 258 need to publish an individual (author-named) internet-draft, because 259 the WG worked directly on the structured specification and obtained 260 consensus on it. 262 Comments from the IETF last call (LC) and the IESG are incorporated 263 in the repository, and new versions of the Internet-Draft are 264 generated for IESG review and submission to the RFC editor. 266 ... 267 | 268 * e3091df (tag:v1.0.0, tag:draft-ietf-wg-proto-02, tag:RFCXXX1) 269 | Responses to IESG comments 270 | 271 * 7494725 (tag:draft-ietf-wg-proto-01) Responses to IETF LC comments 272 | 273 * 8e2be54 (tag:proto-2, tag:draft-ietf-wg-proto-00) 274 | Responses to WGLC comments 275 | 276 * 9703a60 (tag:proto-1) Responses to comments at IETF meeting 277 | 278 * 2b83977 Responses to J. Smith comments 279 | 280 * 8b75e1e (tag:proto-0) Responses to BoF comments 281 | 282 * 1991498 Initial submission 284 The WG adds two features to the specification. The first feature is 285 major enough that the chairs decide it needs IETF consensus, 286 resulting in a second Internet-Draft going through the IETF consensus 287 process (draft-ietf-wg-proto-feature-00) to become an RFC (RFC XXX2). 288 The second feature is minor enough that it can be approved by WG 289 consensus. 291 ... 292 | 293 * a5f3214 (tag:v1.2.0) Merge branch 'v1.2' 294 |\ 295 | * 8fb9cb6 Responses to WGLC comments on feature Y 296 | | 297 | * 39322e9 (tag:featureY-1) Responses to WG comments; ready for WGLC 298 | | 299 | * 39322e9 Add feature Y 300 |/ 301 * d1d201d (tag:v1.1.1) Fix validation errors 302 | 303 * 6571483 (tag:v1.1.0, tag:draft-ietf-wg-proto-feature-04, 304 | tag:RFCXXX2) Merge branch 'v1.1' 305 |\ 306 | * abc3f5e (tag:draft-ietf-wg-proto-feature-03) Resolution of DISCUSSes 307 | | from Security AD 308 | | 309 | * 3ab54f3 (tag:draft-ietf-wg-proto-feature-02) Resolution of DISCUSSes 310 | | from Internet and Transport ADs 311 | | 312 | * cabb1f6 (tag:draft-ietf-wg-proto-feature-01) Responses to WGLC 313 | | and IETF LC comments on feature X 314 | | 315 | * fbfaa6b (tag:featureX-0, tag:draft-ietf-wg-proto-feature-00) 316 | | Responses to comments on feature X 317 | | 318 | * 0630638 Add feature X 319 |/ 320 * e3091df (tag:v1.0.0, tag:draft-ietf-wg-proto-02, tag:RFCXXX1) 321 | Responses to IESG comments 322 | 323 ... 325 The WG develops a major revision of the protocol, resulting in a 326 third Internet-Draft (draft-ietf-wg-protobis-00) going through the 327 IETF consensus process, resulting in RFC XXX3. 329 ... 330 | 331 * a9d7d29 (tag:v2.0.0, tag:draft-ietf-wg-protobis-01 tag:RFCXXX3) 332 | Merge branch 'v2' 333 |\ 334 | * df5d437 (tag:draft-ietf-wg-protobis-00) Responses to 335 | | WGLC and IETF LC comments 336 | | 337 | * 986ebb6 (tag:v2.0.0-beta-1) Checkpoint for hackathon 338 | | 339 | * d86986e (tag:v2.0.0-beta-0) Some more v2 features 340 | | 341 | * ca02154 Restructure for v2 342 |/ 343 * a5f3214 (tag:v1.2.0) Merge branch 'v1.2' 344 | 345 ... 347 This example history is greatly simplified. In a real WG, there will 348 be far more commits without versions, as the WG incorporates 349 proposals, edits, explanatory text, etc. But this example highlights 350 the key moments in the life-cycle of a specification. 352 5. Creating Internet-Drafts from a Repository 354 As noted above, WGs should have one repository per specification. 355 Over the lifetime of the specification, it will be necessary for 356 automated tools to build Internet-Drafts from this repository. A 357 standardized repository layout can help automate this process. 359 The root level of the repository should have a file named "index.xml" 360 or "index.md", depending on whether XML [1] or Markdown [2] is being 361 used. This file should itself be a valid source for an Internet- 362 Draft, including information about the title to be used, authors' / 363 editors' names, security considerations, etc. It will act as a 364 template into which the structured specification will be included 365 when an Internet-Draft is created. 367 The template file should include files that comprise the structured 368 specification as figures at appropriate points in the draft. The 369 Markdown syntax provided by "mmark" provides a syntax for including 370 code fragments [3] from external files, including the ability to 371 selectively include parts of a file. 373 6. References 375 6.1. URIs 377 [1] https://tools.ietf.org/html/rfc7991 379 [2] https://github.com/miekg/mmark/wiki/Syntax 381 [3] https://github.com/miekg/mmark/wiki/Syntax#including-code- 382 fragments 384 Authors' Addresses 386 Benoit Claise 387 Cisco 389 Email: bclaise@cisco.com 391 Richard Barnes 392 Cisco 394 Email: rlb@ipv.sx 396 Joe Clarke 397 Cisco 399 Email: jclarke@cisco.com