Semantic Versioning and Structure for IETF Specifications
draft-claise-semver-01

Network Working Group                                          B. Claise
Internet-Draft                                                 R. Barnes
Intended status: Standards Track                               J. Clarke
Expires: January 19, 2018                                          Cisco
                                                           July 18, 2017

       Semantic Versioning and Structure for IETF Specifications
                         draft-claise-semver-01

Abstract

   In the Internet engineering ecosystem, there is increasingly a need
   for specifications that evolve over time, and which are encoded
   directly in structured formats (e.g., YANG models).  Internet-Drafts
   are a poor fit for working groups that want to produce structured
   specifications, and publishing versions of an evolving specification
   as RFC makes it difficult to track the specification over time.  This
   document outlines recommendations for how working groups can provide
   consistent, meaningful versions for specifications over time and work
   directly on structured documents while still fitting within
   established IETF processes.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on January 19, 2018.

Copyright Notice

   Copyright (c) 2017 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of

Claise, et al.          Expires January 19, 2018                [Page 1]
Internet-Draft                   SemVer                        July 2017

   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Managing Semantic Versions  . . . . . . . . . . . . . . . . .   3
     2.1.  Versioning for Work in Progress . . . . . . . . . . . . .   4
   3.  IETF Consensus for Structured Specifications  . . . . . . . .   5
   4.  Example history . . . . . . . . . . . . . . . . . . . . . . .   6
   5.  Creating Internet-Drafts from a Repository  . . . . . . . . .   8
     6.1.  URIs  . . . . . . . . . . . . . . . . . . . . . . . . . .   9
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   The pace at which the software that drives the Internet is developed
   and deployed today is much faster than it was early in the Internet's
   history.  In this environment, maintaining interoperability can be
   more challenging.

   Two of the major mechanisms that have been developed for driving
   interoperability in a more dynamic ecosystem are structured
   specifications and semantic versioning.  Structured specifications
   allow much of the work of implementing a specification to be
   automated, so that developers can focus on the parts of a
   specification that really need human involvement.  Semantic
   versioning helps operators know what versions can be deployed without
   breaking running systems, so that they can safely deploy updated
   versions of a specification more quickly.

   The traditional practices of the IETF interact poorly with these
   mechanisms.  Each document presented to the IETF for last call and
   IESG approval must be formatted as an Internet-Draft, i.e., as
   unstructured text.  All RFCs across the IETF share a single, common
   numbering space, so that RFC numbers have no useful semantic with
   respect to versioning.  Nonetheless, there is still a need to be able
   to capture the consensus of the IETF at critical points in the life-
   cycle of a specification.

   This document describes recommendations for how a working group (WG)
   that wishes to produce structured specifications with semantic
   version numbers can interact best with IETF processes.

Claise, et al.          Expires January 19, 2018                [Page 2]
Internet-Draft                   SemVer                        July 2017

2.  Managing Semantic Versions

   While some of this process might apply to completely new work (such
   as a YANG module), the process in this document applies to WG adopted
   work items or to modification of an existing IETF-approved work item
   (typically a bis document).

   We start from the premise that a working group controls a version-
   controlled repository (e.g., Git, SVN, etc.) for a structured
   specification (not formatted as an Working Group Internet-Draft), and
   can "tag" commits in the repository as having certain version
   numbers.  We assume that there is one repository per specification,
   so that version tags don't need to state the specification to which
   they refer.

   The recommended structure for semantic versions follows the widely-
   used three-part convention, with an additional field for use in
   working group processes:

     MAJOR.MINOR.PATCH

   The fields in such a structured version have the following semantics
   (cf.  semver.org):

   o  MAJOR is incremented when the new version of the specification is
      incompatible with previous versions.

   o  MINOR is incremented when new functionality is added in a manner
      that is backward-compatible with previous versions.

   o  PATCH is incremented when bug fixes are made in a backward-
      compatible manner.

   In IETF terms, this versioning scheme provides functionality
   analogous to several parts of the traditional IETF process.

   o  MAJOR is analogous to an "obsoletes" relation between RFCs

   o  MINOR is analogous to an "updates" relation between RFCs

   o  PATCH is analogous to use of the RFC errata process

   The more major a change to the specification, the more consensus is
   required.  When the WG wants to make a MAJOR change to a structured
   specification, the specification MUST be converted into Internet-
   Draft format and run through the typical IETF consensus process.
   Every commit that is tagged with a MAJOR version change MUST also

Claise, et al.          Expires January 19, 2018                [Page 3]
Internet-Draft                   SemVer                        July 2017

   have a tag of the form "RFC-XXXX" indicating the number of the RFC
   describing the change.

   MINOR changes follow the same rules, except that the Area Director
   for the WG MAY approve the issuance of a minor version with only WG
   consensus, not full IETF consensus.  Any change to the structured
   specification that significantly changes the security considerations
   for the protocol or requires additional IANA actions MUST be
   converted into Internet-Draft format and submitted for IETF
   consensus.  With the approval of the AD for the WG, changes without
   such impacts MAY be approved by consensus of the working group.

   PATCH-level changes MAY be made by the editors, with the consent of
   the WG chairs.

   When a working group starts up work on a new version of the
   specification, regardless of whether it's a minor update or a
   complete rewrite, they SHOULD create a dedicated branch of the
   repository for the new version, where changes related to the new
   version will be committed.  The semantic version, i.e. MAJOR and
   MINOR is assigned when this branch is merged back to the main
   specification.  Once there is consensus to update the main
   specification to that version, the branch should be merged, and the
   merge commit tagged with the new version number.

   When working on modification to an existing work item (typically a
   bis document), the process is to fork a git repo, branch, make a
   proposal, then push the branch back over to the Working Group when/if
   the Working Group adopts it.

2.1.  Versioning for Work in Progress

   It can be useful to mark certain versions of a work in progress as
   checkpoints, e.g., for reference at a hackathon.  These checkpoints
   should follow their own version sequence, much like Internet drafts:

     LABEL-VERSION

   o  LABEL is a string that identifies the feature branch

   o  VERSION is incremented whenever a new revision is tagged

   These tags are analogous to Internet-Draft names.  Much like an
   Internet-Draft name, the choice of LABEL values is up to the editors
   and WG chairs.  For cases expected to result in a given version, they
   may choose to use that as a label value.  For example, if the WG has
   agreed to embark on a major revision to the protocol, then they might

Claise, et al.          Expires January 19, 2018                [Page 4]
Internet-Draft                   SemVer                        July 2017

   use the label "v2.0.0-beta", so that the working revisions would be
   "v2.0.0-beta-0", "v2.0.0-beta-1", etc.

   It's important to note that not every commit needs a version.  Much
   like working groups using Github to manage Internet-Drafts today only
   periodically submit them to the IETF, a WG can do work in a
   repository and only tag versions when they are useful to the WG.
   Beta versions should be tagged at key points in the development
   process:

   o  Before an IETF meeting or WG interim meeting

   o  Before a hackathon or interop event

   o  Before a working group or IETF last call

   Work on a new version SHOULD be conducted on a dedicated branch.
   Once there is consensus to update the main specification to that
   version, the branch should be merged, and the merge commit tagged
   with the new version number.

3.  IETF Consensus for Structured Specifications

   While working groups may use any format for specifications under
   development, the Internet Standards process requires that a document
   proposed as an RFC must be submitted in the RFC format, i.e., as
   unstructured text.  Proposed RFCs are also required to contain
   explanatory text not typically contained in structured
   specifications, most notably Security Considerations and IANA
   Considerations.  Thus, a working group that is focused mainly on a
   structured specification will have to convert the structured
   specification to the RFC format and add the additional explanatory
   text.

   In order to keep the repository as the primary home for the
   specification, the working group should keep any required explanatory
   text in the repository alongside the structured specification, and
   use automated tools to generate an RFC-formatted document from the
   artifacts in the repository.  As the outputs are reviewed in the IETF
   last call and IESG processes, the editors should reflect their
   responses in the repository, generating updated versions of the RFC-
   formatted document as necessary.

   Whenever an Internet-Draft is generated from the repository, the
   corresponding commit in the repository should be tagged with the full
   name and version of the Internet-Draft.  Additionally, a reference to
   the repository (e.g., a URL) should exist in the text of the

Claise, et al.          Expires January 19, 2018                [Page 5]
Internet-Draft                   SemVer                        July 2017

   resulting Internet-Draft.  These steps enable the evolution of the
   draft to easily be tied back to the evolution of the repository.

4.  Example history

   The below sequence of commits and tags shows the progress of a
   structured specification through several stages of its life-cycle.
   (Time flows up from the bottom, as is common in version control logs;
   most recent is on top.)

   An initial version of a protocol is proposed for a Birds of a Feather
   (BoF) and a WG is formed.  The WG develops version 1.0.0 of the
   specification.  Along the way, they tag betas when they need an easy
   way to refer to a version, e.g., before working group last call
   (WGLC).

   Once the WG has reached consensus, an Internet-Draft is created from
   the repository (draft-ietf-wg-proto-00) and submitted for the IETF
   consensus process, resulting in an RFC (RFC XXX1) that describes the
   first version of the protocol.  In this example, there is never a
   need to publish an individual (author-named) internet-draft, because
   the WG worked directly on the structured specification and obtained
   consensus on it.

   Comments from the IETF last call (LC) and the IESG are incorporated
   in the repository, and new versions of the Internet-Draft are
   generated for IESG review and submission to the RFC editor.

   ...
   |
   * e3091df (tag:v1.0.0, tag:draft-ietf-wg-proto-02, tag:RFCXXX1)
   |         Responses to IESG comments
   |
   * 7494725 (tag:draft-ietf-wg-proto-01) Responses to IETF LC comments
   |
   * 8e2be54 (tag:proto-2, tag:draft-ietf-wg-proto-00)
   |         Responses to WGLC comments
   |
   * 9703a60 (tag:proto-1) Responses to comments at IETF meeting
   |
   * 2b83977 Responses to J. Smith comments
   |
   * 8b75e1e (tag:proto-0) Responses to BoF comments
   |
   * 1991498 Initial submission

   The WG adds two features to the specification.  The first feature is
   major enough that the chairs decide it needs IETF consensus,

Claise, et al.          Expires January 19, 2018                [Page 6]
Internet-Draft                   SemVer                        July 2017

   resulting in a second Internet-Draft going through the IETF consensus
   process (draft-ietf-wg-proto-feature-00) to become an RFC (RFC XXX2).
   The second feature is minor enough that it can be approved by WG
   consensus.

...
|
*   a5f3214 (tag:v1.2.0) Merge branch 'v1.2'
|\
| * 8fb9cb6 Responses to WGLC comments on feature Y
| |
| * 39322e9 (tag:featureY-1) Responses to WG comments; ready for WGLC
| |
| * 39322e9 Add feature Y
|/
*   d1d201d (tag:v1.1.1) Fix validation errors
|
*   6571483 (tag:v1.1.0, tag:draft-ietf-wg-proto-feature-04,
|           tag:RFCXXX2) Merge branch 'v1.1'
|\
| * abc3f5e (tag:draft-ietf-wg-proto-feature-03) Resolution of DISCUSSes
| |         from Security AD
| |
| * 3ab54f3 (tag:draft-ietf-wg-proto-feature-02) Resolution of DISCUSSes
| |         from Internet and Transport ADs
| |
| * cabb1f6 (tag:draft-ietf-wg-proto-feature-01) Responses to WGLC
| |         and IETF LC comments on feature X
| |
| * fbfaa6b (tag:featureX-0, tag:draft-ietf-wg-proto-feature-00)
| |         Responses to comments on feature X
| |
| * 0630638 Add feature X
|/
* e3091df (tag:v1.0.0, tag:draft-ietf-wg-proto-02, tag:RFCXXX1)
|         Responses to IESG comments
|
...

   The WG develops a major revision of the protocol, resulting in a
   third Internet-Draft (draft-ietf-wg-protobis-00) going through the
   IETF consensus process, resulting in RFC XXX3.

Claise, et al.          Expires January 19, 2018                [Page 7]
Internet-Draft                   SemVer                        July 2017

   ...
   |
   * a9d7d29 (tag:v2.0.0, tag:draft-ietf-wg-protobis-01 tag:RFCXXX3)
   |         Merge branch 'v2'
   |\
   | * df5d437 (tag:draft-ietf-wg-protobis-00) Responses to
   | |         WGLC and IETF LC comments
   | |
   | * 986ebb6 (tag:v2.0.0-beta-1) Checkpoint for hackathon
   | |
   | * d86986e (tag:v2.0.0-beta-0) Some more v2 features
   | |
   | * ca02154 Restructure for v2
   |/
   *   a5f3214 (tag:v1.2.0) Merge branch 'v1.2'
   |
   ...

   This example history is greatly simplified.  In a real WG, there will
   be far more commits without versions, as the WG incorporates
   proposals, edits, explanatory text, etc.  But this example highlights
   the key moments in the life-cycle of a specification.

5.  Creating Internet-Drafts from a Repository

   As noted above, WGs should have one repository per specification.
   Over the lifetime of the specification, it will be necessary for
   automated tools to build Internet-Drafts from this repository.  A
   standardized repository layout can help automate this process.

   The root level of the repository should have a file named "index.xml"
   or "index.md", depending on whether XML [1] or Markdown [2] is being
   used.  This file should itself be a valid source for an Internet-
   Draft, including information about the title to be used, authors' /
   editors' names, security considerations, etc.  It will act as a
   template into which the structured specification will be included
   when an Internet-Draft is created.

   The template file should include files that comprise the structured
   specification as figures at appropriate points in the draft.  The
   Markdown syntax provided by "mmark" provides a syntax for including
   code fragments [3] from external files, including the ability to
   selectively include parts of a file.

Claise, et al.          Expires January 19, 2018                [Page 8]
Internet-Draft                   SemVer                        July 2017

6.  References

6.1.  URIs

   [1] https://tools.ietf.org/html/rfc7991

   [2] https://github.com/miekg/mmark/wiki/Syntax

   [3] https://github.com/miekg/mmark/wiki/Syntax#including-code-
       fragments

Authors' Addresses

   Benoit Claise
   Cisco

   Email: bclaise@cisco.com

   Richard Barnes
   Cisco

   Email: rlb@ipv.sx

   Joe Clarke
   Cisco

   Email: jclarke@cisco.com

Claise, et al.          Expires January 19, 2018                [Page 9]